View Source

JCSDA-Internal: https://github.com/JCSDA-internal

JCSDA-Core: https://github.com/JCSDA-internal/JCSDA-core

Table of Contents

New employee GitHub setup

Information on how to get GitHub set up as a new employee can be found at the JCSDA-Core Onboarding Wiki. If you are so new and cannot see this page yet, your team lead will need to add you to the JCSDA-internal and JCSDA repositories.

JCSDA Repository Development

When contributing to a JCSDA repository, you will clone the repo and create a branch with your changes. Then issue a Pull Request (PR) with at least 2 reviewers before it can be merged back into the develop branch. This section contains a simple outline of the commands used to do that. More information can be found in the JEDI documentation Best Practices for Developers.

To clone a repository (if not already done so): git clone https://github.com/JCSDA-internal/<repo_name>
To check which branch you are on: git branch -a
To checkout a new branch: git checkout -b feature/<branch_name>
To check the status of your branch and changes made: git status
To stage all of the files modified for a commit: git add --all
To make a commit with a useful description: git commit -m "add description of change here"
When ready to create a PR or draft PR, push your branch back to the origin: git push -u origin feature/<branch_name>
Next go to the GitHub url and create a PR from the new branch, be sure to add your team's designated tags (such as "INFRA") and other necessary fields

Other useful commands:

Stashing
- To "stash" or save work for later: git stash
- To see what you have stashed: git stash list
- To retrieve your stashed work: git stash apply stash@{2}
- Helpful stash article can be found here
Branch edits
- To see changes made to an existing file: git diff path/to/filename
- To restore one modified file: git restore path/to/filename
- To restore all uncommitted edits of the branch: git restore .

Credentials

Before doing a JEDI build or development, it is a good idea to set up your GitHub credentials. This can be done by following this section in the JEDI documentation.

GitHub Forks

Forks need be enabled by the repo admins
Click on forks to create your own fork (in your private account, not in any organization you have write access to), if you already have a fork it will take you there
Forks are snapshots of the original repository at the time the fork was created
Consider forks as nothing more than a staging area for your development branches in order to create PRs to the authoritative repository.
- Branches/tags that come with the authoritative repo when forked are useless and a distraction, best to get rid of all of them/not copy them in the first place.
- But need a default branch: either keep the default branch from the authoritative repo and choose to ignore it, or rename it (“dummy”)
By default, Github allows updates to PRs for repo maintainers that are made from your fork with a branch: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork
- This can be disabled (safer; https://github.com/orgs/community/discussions/5587) but hampers PR progress (repo admins cannot push updates from develop before merging)
Benefits of forks:
- Much cleaner permissions on authoritative repositories, especially if public. Everyone has read access (or what the repo owners decide to be the default). Only repo administrators and maintainers need special permissions, but consider “triage” for real collaborators
- No need to administrate and clean up branches in authoritative repositories. Admins/maintainers create and manage develop, release, and dedicated branches for a special purpose (e.g. a code sprint branch)
Disadvantages of forks:
- Slightly more complicated git workflow, because users need to handle multiple remote repositories in their local clones; but: simple tools can help - see for example: https://github.com/climbfuji/domtools/tree/develop/github

Git Submodules

Git repositories can track other components as submodules. They always point at a particular hash that needs to be advanced explicitly.

Common pitfall: one of these sets of commands is NOT the same as the others! The last command is missing git submodule update --recursive

git clone -b release/1.4.0 --recursive https://github.com/jcsda/spack-stack

git clone -b release/1.4.0 https://github.com/jcsda/spack-stack
cd spack-stack
git submodule update --init --recursive

git clone --recursive https://github.com/jcsda/spack-stack
cd spack-stack
git checkout origin/release/1.4.0

Advantages of git submodules
- Full reproducibility, checking out a hash of the top-level repo means one always gets the hashes that were committed to it (and hopefully tested!)
- A top-level git status shows changes in submodules, even if nested
- Never end up with broken configuration (i.e. checking out between two repos with associated PRs are merged can’t happen)
Danger zone: equivalent to make update
- In top-level repository, after
  git remote update && git [pull|checkout] remote-name[/]develop
- This forwards all submodules recursively to the heads of the branches in (each of the) .gitmodules (files):
  git submodule update --recursive --remote
- Should not be needed, because
  git submodule update --recursive
  achieves the same if code is committed correctly, plus it doesn’t break (nested) submodules where fixed hashes are used

- If really needed use explicitly for individual submodules:
  git submodule update --recursive --remote submodule-name
Disadvantages
- Confusing at first, especially when combined with forks
Best practices
- Always keep .gitmodules in sync with the actual submodule pointer
  - Guarantees that automated and manual tests use the same code
  - Serves as documentation that other PRs may need to be merged first
- Limit the number of nested submodules - life is easier that way
  - Needs cascading merges w/ submodule pointer updates
Another common pitfall:
- Changes to .gitmodules need to be committed first before git “sees” them (same as for .gitignore)