DRAFT  – PLEASE COMMENT

Speculative Long-term Development is any development intended for ACME AND its not clear when or if it will be officially added to a future version of the model.  For this discussion, "Officially Added" means it is on master, can be turned on using appropriate configuration options, and tests of that feature must pass for any other development (the test becomes part of acme_developer or acme_integration). Examples of speculative long-term development include ACME developments for 2+ versions ahead of current version,  developments from other programs (CMDV, ECP).

The ACME SE group has some recommended procedures for doing speculative development.  Which one to use depends on the nature of your code development.

IF your feature touches many files and alters data types of a main model, you should do direct development in master.

IF your feature is isolated in a single subroutine and you are not changing datatypes, you can probably use long-lived branches.

If your feature is not speculative – it will definitely be in ACME – but will take a long time, you should develop directly in master.

Development in ACME-Climate/ACME (recommended)

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.

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)

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.

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

1. Start a branch for your development as is done for any ACME development.
2. As you develop code on your branch, make a test or tests for your feature
3. Keep your branch up-to-date by the following:
   
   1. PREFERRED: Periodically rebase your branch to the head of master (or head of the integration branch)
   2. OR you can merge master to your long-lived branch IF AND ONLY IF:
      1. A subroutine or function your feature depends on has changed its API OR
      2. A tag has been made on ACME master (so you get a known state).   Do NOT make random "oh its been a while" merges of master to your branch.
      3. DO NOT merge from master just for machine config updates.  Cherry pick those or copy them.
4. Run acme_developer on your branch along with tests for your feature as development proceeds.
5. When finished, make a PR as for normal ACME development.

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.