We use a feature branch work flow. The following description is borrowed from Understanding the GitHub flow.
When you're working on APSIM, you're going to have a bunch of different features or ideas in progress at any given time – some of which are ready to go, and others which are not. Branching exists to help you manage this workflow.
When you create a branch in your project, you're creating an environment where you can try out new ideas. Changes you make on a branch don't affect the
master branch, so you're free to experiment and commit changes, safe in the knowledge that your branch won't be merged until it's ready to be reviewed by someone you're collaborating with.
Branching is a core concept in Git, and the entire GitHub Flow is based upon it. There's only one rule: anything in the
master branch is always deployable. Because of this, it's extremely important that your new branch is created off of master when working on a feature or a fix. Your branch name should be descriptive (e.g.,
feature/new-maize-model), so that others can see what is being worked on. It is always good to start the feature with 'feature/'. The Branch button in SourceTree can be used to create a branch. Your current branch is in bold in SourceTree.
To switch between branches, commit your changes and then double click the branch you want to switch to. Branches are independent of each other. Your changes on one branch will be unavailable in the other branch. At this stage the branches only exist on your GIT clone on your hard disk.
Once your branch has been created, it's time to start making changes. Whenever you add, edit, or delete a file, you're making a commit, and adding them to your branch. This process of adding commits keeps track of your progress as you work on a feature branch.
Commits also create a transparent history of your work that others can follow to understand what you've done and why. Each commit has an associated commit message, which is a description explaining why a particular change was made. Furthermore, each commit is considered a separate unit of change. This lets you roll back changes if a bug is found, or if you decide to head in a different direction.
Commit messages are important, especially since Git tracks your changes and then displays them as commits once they're pushed to the server. By writing clear commit messages, you can make it easier for other people to follow along and provide feedback.
Commits are local only until you do a push.
Push changes to a remote
Once you're ready make changes available to others, you will need to push your commits to a 'remote' repository. This is usually your ApsimX fork. Doing this won't impact on other developers and won't cause Jenkins to run the test suite. You can do this as many times as you wish.
Open a Pull Request
Pull Requests initiate discussion about your commits. Because they're tightly integrated with the underlying Git repository, anyone can see exactly what changes would be merged if they accept your request.
You can open a Pull Request at any point during the development process: when you have little or no code but want to share some screenshots or general ideas, when you're stuck and need help or advice, or when you're ready for someone to review your work. By using GitHub's @mention system in your Pull Request message, you can ask for feedback from specific people or teams, whether they're down the hall or ten time zones away.
Pull Requests are useful for contributing to open source projects and for managing changes to shared repositories. Pull Requests provide a way to notify project maintainers about the changes you'd like them to consider. They can also help start code review and conversation about proposed changes before they're merged into the master branch.
Jenkins will automatically run all pull requests and flag pass/fail with GitHub. If you have finished a piece of work then you need state somewhere in the body of the pull request:
This will alert the administrators of the APSIM repository that the pull request fixes issue number 45. All merges to master must have an issue describing the piece of work. The administrators will then merge the pull request with the master branch of the main repository and close the issue. Once the issue is closed it should not be reopened.
Diagram of Process
Developers work in their own branch, in their cloned repository on their computer.If they have performed commits in their branch on their hard disk and want to get the latest changes from one of the remotes they should rebase to a particular revision of a remote repository; usually this is the master branch on the MAIN ApsimX repository. When they want to share their branch with another user or to merge it with the MAIN ApsimX repository, they will need to push to their GitHUB fork and issue a pull request inviting others to look at the changes on the branch or for it to be considered for merging with the MAIN master branch.
Consider this example screenshot:
I have configured my 2 remotes as MAIN (https://github.com/APSIMInitiative/ApsimX) and my fork as hol353 (https://github.com/hol353/ApsimX) - highlighted under remotes in the screenshot. I am in the middle of a piece of work in a branch called feature/soil-rework. This branch (middle highlight in the tree) is currently behind MAIN/master (top highlight in the tree) i.e. other developers have committed/pushed and merged their work to MAIN/master since I started working on my changes. What I should do is to rebase my branch on my computer to the revision that MAIN/master is at. To do this in SourceTree I make sure my branch is current on my computer (soil-rework is bolded under Branches, feature). I think right click on the MAIN/master revision at the top of the tree (highlighted) and select rebase. This will make my branch relative to that revision rather than the older one on 23 Apr 2015 12:29. The result is shown below: