Workflow - AletheiaWareLLC/PerspectiveSuite GitHub Wiki
PerspectiveSutie is composed of this repo and a set of submodules, therefore the workflow is somewhat different from projects that don't use submodules. Check out the links below to get a better understanding of submodules:
The basic workflow used for PerspectiveSuite is that the latest version of the code is always origin/master. To fix a bug or add a feature the developer creates a branch (possibly in a fork), usually off the latest master branch. When the change is ready for to be reviewed the changed pushed as a single commit (rebase onto latest master and use --force when pushing if necessary). If this is first change for this branch, create a pull request to start the review process.
When the pull request is approved, then a person with write access to the repo
uses the github Rebase and Merge button to merge the change into master and
delete the development branch. The goal is that each commit on master compiles,
passes all tests, and runs on all applicable devices, while ensuring the git
history is clean and linear.
One of the nice things about using submodules is that the above workflow can all
be done within the PerspectiveSutie itself. From a PerspectiveSuite checkout simply
cd <submodule> and follow the basic workflow above.
After a submodule fix/feature is approved and merged into the submodule's master
branch it will still not be part of PerspectiveSuite. Any user that invokes
git clone --recursive https://github.com/AletheiaWareLLC/PerspectiveSuite.git will
NOT get see changes. This is actually great news because a particular change
may require changes across multiple submodules and the goal is that every commit should
run and pass all tests. Using submodules makes it easy to attain this goal.
During testing and development of the submodule changes there will also be a development branch for PerspectiveSuite. The name of this branch is usually the same name as used in the submodules, but that is convention only. To test the changes to submodule(s) and PerspectiveSuite you need to create a commit with not only any changes to PerspectiveSuite itself but also any changes to the special commits that point to the associated commit in the submodules defined by its SHA-1.
For example, below the current directory is PerspecitveSuite and we're on
the add-feature branch. We've have new commits on submodule JavaCommon (new commits)
as well as PerspectiveSuite README.md.
$ git status
On branch add-feature
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git restore <file>..." to discard changes in working directory)
modified: JavaCommon (new commits)
modified: README.md
no changes added to commit (use "git add" and/or "git commit -a")
We now use our basic workflow on PerspecitveSuite and will finish the new
feature when this final commit is merged to PerspectiveSuite/master. At that
point any git clone --recursive of PerspecitveSuite will see the new feature.
The final step is for other developers to pull, synchronize and update the repo and all submodules with:
$ ./gradlew sync
What sync does is:
$ git pull origin master # Pull origin master from `PerspectiveSuite/`
$ git submodule sync --recursive # Sync any meta data changes to .git/modules
$ git submodule update --init --recursive # Update to latest version of all submodules
You can also add the above as an alias to the global configuration with:
$ git config --global alias.sync '!git pull origin master && git submodule sync --recursive && git submodule update --init --recursive'
And then the command it will be:
git sync