Presenters-0697
Abstract
In this webinar, we will demonstrate how to make a contribution to a community open-source repository. Using a live demo, we will walk through the process, starting from making edits to your local copy of the source code, through to submitting them as a “pull request” and going through the review process. We will illustrate how to walk through the various steps: posting an issue, making a local code branch (and/or fork), running unit tests, pushing changes to the remote repository, creating a pull request, understanding results of Continuous Integration tests, and managing a code review.
Checklist from issue to pull request:
Make an issue (if there isn't already one)
It's good practice to start any change with an Issue on the Landlab GitHub repository's Issues tab.
- Sign on to GitHub
- Navigate to the Landlab repository
- Select the Issues tab, then the New Issue button
In the first example, I'm going to address Issue #2258 "Correct parameterization of DepthDependentLinearDiffuser"
Make a fork of the Landlab repository
- Sign on to GitHub
- Navigate to https://github.com/landlab/landlab
- Click the Fork button to create a fork of the repository in your own GitHub space
Clone your fork to your local machine
- Navigate to your forked version of the repository. For example, my GitHub username is gregtucker, so I navigate to https://github.com/gregtucker/landlab. This is my fork.
- Use the Code => Clone button to copy the clone address
- In a Terminal (i.e., UNIX shell) on your local machine, navigate to the folder that will contain the local version of your Landlab fork. Example for me:
cd ~/Documents/Talks/2025/Webinar-contributing-to-csdms
- Type git clone and then paste in the address you copied from GitHub. Example for me:
git clone git@github.com:gregtucker/landlab.git
Create a branch for your edits or additions
Example: git checkout -b gt/update-ddepdiff-init
Make edits / additions on your local copy
Run linters
If you have changed or added code files and/or Jupyter notebooks, run the linting tools:
- black
- flake8
and the equivalents for Jupyter notebooks if relevant.
Make a "news frag" file
To keep track of additions and changes, Landlab uses "news fragments": tiny little files that contain a record of each change. To add a news fragment for your additions/changes, navigate to the landlab/news folder. Create a file whose name is the Issue number that you are addressing, plus a file extension that has one of the following:
- bugfix for a bug fix
- doc for a documentation improvement
- feature for a new feature (such as a new component)
- removal for removal or deprecation of a public-facing feature
- misc for everything else
In this example, it's somewhere between a bug fix (it's not technically a bug, but could be misleading), a documentation improvement (it's no longer misleading!), and a removal (because we're getting rid of the old name of a parameter). Since it's not totally clear, I'll just call this misc. My example is responding to Issue #2258, so my news frag file will be:
2258.misc
Inside the file I'll put a one-line description, something like:
Correct the header doc and soil-velocity parameter name in DepthDependentLinearDiffuser.
Run the tests locally
(See: https://landlab.csdms.io/install/developer_install.html#install)
From the main Landlab folder:
- Lint: nox -s lint (runs the linters to make sure code is clean and consistent)
- News frag: nox -s towncrier (checks to make sure there's a valid news frag)
- Code: nox -s test (this one takes a few minutes)
- Jupyter notebooks: nox -s test-notebooks (also takes a bit of time)
- Docs: nox -s build-docs (if you've changed any documentation, including inline)
Once all your tests are passing locally, you are ready to push to your remote fork.
Push to your remote fork
Once you've made and committed your changes with git, and the tests are all passing locally, push your changes to your remote fork.
Example:
git push origin gt/update-ddepdiff-init
Activate a Pull Request
Returning to your browser, check your fork's GitHub page. You should see a yellow banner with a message that reads something like "gt/update-ddepdiff-init had recent pushes 3 seconds ago", and a green button labeled "Compare & pull request".
Press this button to activate a pull request for your changes.
This takes you to the main Landlab repository page on GitHub. Here you can:
- Give your Pull Request a title
- Describe your Pull Request
- Change it to a DRAFT Pull Request (using the arrow on the green Create Pull Request button)
Once you've done those steps, click the green Draft pull request button. This will activate a series of automated tests.
What Makes a Good Pull Request
- Small and focused: Address one issue or feature per pull request. Avoid bundling multiple unrelated changes.
- Clear purpose: The pull request should explain why a change is needed, not just what was changed.
- Draft first: Open your pull request in draft mode so others can follow progress and provide early feedback.
- Readable history: Prefer a clean commit history. Consider squashing or rebasing before final review.
- Well-tested and documented: All code changes should be accompanied by appropriate tests and updated documentation.
Requesting a review
Once your tests have all passed, it's time to get your Pull Request reviewed. In theory, a CSDMS staff member should be alerted to the newly submitted Pull Request, but best practice is to be proactive: request a review!
A good way to do this add a Comment (see bottom of your Pull Request page), in which you request a review(s).
If you're not sure who should review it, just write something like: "Could someone at CSDMS review this please?"
If you know of particular people that you would love to get a review from, go ahead and tag them by their GitHub username. For example, if I might ask for reviews from CSDMS team members Eric, Mark, and/or Tian, so my comment could be:
"Could @mcflugen, @mdpiper, and/or @gantian127 review this for me please?"
You can also request reviews from other community members - we highly encourage this!
How many reviews?
Your code should be reviewed by at least one person on the development team for the repository in question. Ideally, it's nice to have two or even three, but we don't require this.
The review dance
Just like a journal review, there's often some back-and-forth, with suggestions for (often minor) improvements. Fortunately, "Reviewer 2" won't show up, however - these are friendly reviews!
The final step
Once you and the reviewer(s) are happy with your PR, a member of the development team (usually also a reviewer) will click the magic button that merges your PR into the main development version.
Please acknowledge the original contributors when you are using this material. If there are any copyright issues, please let us know (CSDMSweb@colorado.edu) and we will respond as soon as possible.
Of interest for:
