Some of the subdirectories in the ACME code contain code that was brought in from another repository. List them all.
Terms
- external any subdirectory in ACME whose entire content is from another repository
- upstream master the repository everyone is sending their changes to. Only one so that everyone pulling from the same source is working with all the same changes. The source of an external.
Methods for including externals
- submodule a link that points to another git repository. See Sharing External Code using Git Submodules . Submodules require an extra step after cloning to get the code.
- subtree a set of files and commits from another git repo, brought in to your repo. See Sharing External Code using Git Subtree. Subtrees are included in ACME when you "git clone".
- monorepo adding multiple projects, related or not, in the same repo. Code is included when you clone ACME.
- buildtime the repo is checked out to the $CIME_OUTPUT_ROOT/$CASE/bld when compiling a case for the first time. Code does not exist in ACME repo.
Rules for adding externals
- Group leads must approve adding a new external. The group needing the external can decide on the method of inclusion. A POC for the upstream master must be identified and the SE group leads notified.
- The upstream master for the external must be build-able and testable on its own.
- For submodules, the linked repo must be readable by all ACME developers. If the upstream master can not be made readable, a fork must be maintained in ACME-Climate github and ACME then links to that fork.
Development in externals
In general, there are several ways to develop with external code in ACME
- strict 1-way: all development is merged to the upstream master first and flows down to ACME. No exceptions.
- mostly 1-way: prefer strict 1-way but some exceptions can be made for emergency fixes
- 2-way: developers can make changes in ACME or the upstream master. POC keeps them in sync.
More specific instructions for externals are below. NOTE: a commit should never mix external and non-external code.
Table of Externals currently in ACME
| Name | Subdirectory in ACME | external method | upstream master | development method | POC | Notes |
|---|---|---|---|---|---|---|
| CIME | cime | subtree | https://github.com/ESMCI/cime | 2-way | ||
| MCT | cime/externals/MCT | subtree | https://github.com/MCSclimate/MCT | mostly 1-way | usually brought in with CIME | |
| PIO | cime/externals/pio* | subtree | https://github.com/NCAR/ParallelIO | mostly 1-way | usually brought in with CIME | |
| MPAS-Ocean | components/mpas-o/model | submodule | https://github.com/MPAS-Dev/MPAS forked to https://github.com/ACME-Climate/MPAS | strict 1-way | ||
| MPAS-Land Ice | components/mpasli/model | submodule | https://github.com/MPAS-Dev/MPAS forked to https://github.com/ACME-Climate/MPAS | strict 1-way | Matt Hoffman | |
| MPAS-Sea Ice | components/mpas-cice/model | submodule | https://github.com/MPAS-Dev/MPAS forked to https://github.com/ACME-Climate/MPAS branch cice/develop | strict 1-way | ||
| FATES | components/clm/src/external_models/fates | submodule | https://github.com/NGEET/fates forked to https://github.com/ACME-Climate/fates | strict 1-way | ||
| MPP | components/clm/src/external_models/mpp | submodule | https://github.com/ACME-Climate/mpp branch alm/develop | strict 1-way | Gautam Bisht | |
| HOMME | components/homme | monorepo | NA | NA | Mark Taylor | ACME CAM uses homme/src/share and homme/src/preqx |
| CVMix | NA | buildtime | https://github.com/CVMix/CVMix-src | strict 1-way | ? | After case.build, can be found in $EXEROOT/ocn/source/core_ocean/.cvmix_all |
| ocean BGC | NA | buildtime | https://github.com/ACME-Climate/Ocean-BGC | strict 1-way | ? | After case.build, can be found in $EXEROOT/ocn/source/core_ocean/.BGC_all |
Externals planned for ACME
| Name | Subdirectory in ACME | external method | upstream master | development method | POC | Notes |
|---|---|---|---|---|---|---|
| CICE column physics | TBD | TBD | ? | ? | ? | |
| sBeTR for land model | components/clm/src/external_models/sbetr | submodule | https://github.com/ACME-Climate/sbetr | strict 1-way | Gautam Bisht |
Specific external development instructions
CIME:
Code location: ACME/cime
Any code development in ACME/cime/config/acme can be committed directly to ACME through the normal PR process.
Code development in other parts of CIME should be committed first with a PR in https://github.com/ESMCI/cime. It will be then brought to ACME by a subtree merge as in Maintaining the CIME subtree in ACME.
ACME staff can report any bugs in CIME at https://github.com/ACME-Climate/ACME/issues. SE/CPL staff may open a companion report at https://github.com/ESMCI/cime/issues. ACME cime bugs which have been fixed in ESMCI and are waiting a subtree merge will have the github label "Fixed in ESMCI" attached to them.