Revise documentation on how to use a branch of a component within a CESM checkout
- Dominant language
- Python
- Stars
- 489
- Forks
- 246
- Avg merge
- 16h 44m
- Merged PRs (30d)
- 3
Description
I periodically get questions about how to point to a branch of a component (say, CAM, CTSM or CISM) within a CESM checkout (most recently from @Ivanderkelen). We have some documentation in the [CESM README file](https://github.com/ESCOMP/CESM#3customizing-your-cesm-sandbox), but I'm not sure that what we have is actually the method that makes the most sense. In particular, there are at least two problems with telling people to point to their branch in Externals.cfg:
1. Support for branches with manage_externals still leaves a lot to be desired (see https://github.com/ESMCI/manage_externals/issues/34)
2. Additional problems are caused if you change an Externals.cfg file in the middle of the tree (rather than the top-level file). For example, if you want to point to a different version of FATES (an external of CTSM), you might be tempted to modify the file `components/clm/Externals_CLM.cfg`. However, if you do that, when you rerun manage_externals from the top level (from the root of the CESM clone), you will get an error because the `components/clm` external has a modified file. (@ekluzek has suggested allowing checkout_externals to proceed if there are modifications in these Externals files. This may be worth considering, although it might be hard to implement and the implications should be thought through carefully.)
So I'm inclined to recommend that people checkout their branch using regular git commands. For example, if you want to checkout your branch of CTSM in a CESM checkout, I would recommend getting CESM as normal and doing an initial run of `manage_externals/checkout_externals`. Then do:
```
cd components/clm
git remote add ...
git fetch ...
git checkout ...
```
However, this isn't completely straightforward if your branch is of a component that has its own sub-externals (e.g., you have a branch of CTSM, which has a FATES external). In this case, I would probably still recommend using the above procedure to get your branch, but then getting any sub-externals by running the following from within `components/clm` (NOT from the CESM top level):
```
./manage_externals/checkout_externals clm
```
I'd like to hear some thoughts from others. I don't feel in a rush to update this documentation, so I think it's best if we take some time to gather thoughts until we feel pretty happy with a recommendation for users.
@gold2718 @cacraigucar @nusbaume @ekluzek @Katetc @mnlevy1981 @alperaltuntas @jedwards4b @mvertens @rsdunlapiv @uturuncoglu
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.