...

Development in ACME-Climate/ACME (recommended)

Image Added

1. Split the long-term development in to pieces that can be checked in to master as they are finished.
2. Add pieces back to master with PRs as is done for regular ACME development.
3. When you enough code to execute some of your feature, add a test or tests for it.  These tests won't be added to the main acme test suites until the feature is "officially added".  If you have more then one, they could be part of a separate test suite.  Your PR must still pass the standard ACME testing.
4. Develop the next piece of your feature with a new branch from the head of master.

# If not done yet
git clone git@github.com:ACME-Climate/ACME.git
For each incremental step
git fetch
git checkout master
git pull
# make new branch
git checkout -b username/branchname
# ... develop
# ... test locally
# push changes to master
git add <newfiles>
git commit -a
git push -u origin username/branchname

# Now make PR from ACME github page https://github.com/ACME-Climate/ACME

Feature is always in the ACME source but may not be fully working.  Feature developer is always working with recent master to avoid divergence.   Least painful integration.   Developers of other features can build off of what you've committed to master.

Long-lived integration branch (for 2 or more related features)

Image Added

1. Create an integration branch which will track ACME master.   This can be master on a fork of ACME such as https://github.com/ACME-Climate/ACME-ECP
2. Designate a person to maintain the integration branch.  They will update it with latest ACME master.
3. Make feature branches off of this integration branch.  PR's should be made back to the integration branch.
4. Before merging to the integration branch, test each PR individually using acme_developer plus additional tests for the feature before merging.
5. If testing each PR each day costs to much, you should also make a "next" branch for the integration branch to test multiple PRs nightly.  This may also be necessary if you want more assurance the integration branch is stable.
6. The maintainer should make "mini releases" of the integration branch with a PR back to ACME-Climate/ACME.  (tag the integration branch to mark these).

Feature lives on the integration branch until integration branch is merged to upstream master.  Maintaining the integration branch (with merges from upstream master) could become arbitrarily hard if related codes diverge.  Allows team of developers to work on a large component and stay in sync with each other.  Rest of ACME is unaware of developments until integration branch is merged to master.

Create fork from https://github.com/ACME-Climate/ACME (use 'fork' button)

Development

# Let's assume new fork is https://github.com/MyProject/ACME
git clone git@github.com/MyProject/ACME.git
git fetch
git checkout master
git pull
# make new branch
git checkout -b username/branchname
# ... develop
# ... test locally
# push changes to master
git add <newfiles>
git commit -a
git push -u origin username/branchname

Syncing with ACME master

reference: https://help.github.com/articles/syncing-a-fork/
$ git clone git@github.com/MyProject/ACME.git
$ cd ACME
$ git remote add upstream git@github.com:ACME-Climate/ACME.git
# When updating fork from ACME-Climate/ACME
$ git fetch upstream  (update local ACME-Climate/ACME master, locally labelled 'upstream/master')
$ git checkout master (local MyProject/ACME master)
$ git merge upstream/master (merge in changes from ACME-Climate/ACME)
(resolve any conflicts)
$ git push origin master (push the merged changes to githup repo  git@github.com/MyProject/ACME_Fork.git)

Long-lived branch off of ACME-Climate/ACME master (or from an integration branch)

...

Features lives on your branch until it is finished.   Maintaining the branch (with rebases or occasional merge from master) could become arbitrarily hard if related codes diverge.  Other developers unaware of feature until its finished. 

3a

Image Added

# If not done yet
git clone git@github.com:ACME-Climate/ACME.git
# For each commit
git fetch
git checkout master
git pull
# make new branch
git checkout -b username/branchname
(develop on username/branchname, probably with subbranches)
git push origin username/branchname
# Periodically update master and rebase work
git checkout master
git pull
git checkout username/branchname
git rebase master
(resolve any conflicts)
# push the new  rebased branch back to ACME
git push origin username/branchname
(Tell everyone working on the branch that it's been rebased, everyone should now rename or
delete their local username/branch and check out a fresh version of username/branchname)

3b

Image Added