...
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
...
- 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
- To "stash" or save work for later:
- 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 .
- To see changes made to an existing file:
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
Code Block 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
Code Block 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):
Code Block git submodule update --recursive --remote
Should not be needed, because
Code Block 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:
Code Block git submodule update --recursive --remote submodule-name
- Disadvantages
- Confusing at first, especially when combined with forks
- 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
- Always keep .gitmodules in sync with the actual submodule pointer
- Another common pitfall:
- Changes to .gitmodules need to be committed first before git “sees” them (same as for .gitignore)