ESCOMP / ESCOMP/CESM

Revise documentation on how to use a branch of a component within a CESM checkout

Open
#139 20 comments 0 reactions 0 assignees View on GitHub
documentation
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.