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.

Direct development in master (recommended)

...

1. Create an integration branch which will track ACME master.   This is typically 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 can 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 speculative featurecomponent 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.
2. Make a test or tests for your feature
3. Keep your branch up-to-date
   
   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.

...