Browse wiki
From CSDMS
In this webinar, we will demonstrate how t … 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.</br></br></br></br>'''Checklist from issue to pull request:'''</br><hr></br>'''Make an issue (if there isn't already one)'''<br></br>It's good practice to start any change with an Issue on the Landlab GitHub repository's Issues tab.</br>* Sign on to GitHub</br>* Navigate to the Landlab repository</br>* Select the Issues tab, then the New Issue button</br>In the first example, I'm going to address Issue #2258 "Correct parameterization of DepthDependentLinearDiffuser"</br></br>'''Make a fork of the Landlab repository'''<br></br>* Sign on to GitHub</br>* Navigate to https://github.com/landlab/landlab</br>* Click the '''Fork''' button to create a fork of the repository in your own GitHub space</br></br>'''Clone your fork to your local machine'''<br></br>* 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.</br>* Use the '''Code => Clone''' button to copy the clone address</br>* 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:</br></br>cd ~/Documents/Talks/2025/Webinar-contributing-to-csdms</br></br>* Type git clone and then paste in the address you copied from GitHub. Example for me:</br>git clone git@github.com:gregtucker/landlab.git</br></br>'''Create a branch for your edits or additions'''<br></br>Example: git checkout -b gt/update-ddepdiff-init</br></br>'''Make edits / additions on your local copy'''<br></br>'''Run linters'''<br></br>If you have changed or added code files and/or Jupyter notebooks, run the linting tools:</br>* black</br>* flake8</br>and the equivalents for Jupyter notebooks if relevant.</br></br>'''Make a "news frag" file'''<br></br>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:</br></br>* bugfix for a bug fix</br>* doc for a documentation improvement</br>* feature for a new feature (such as a new component)</br>* removal for removal or deprecation of a public-facing feature</br>* misc for everything else</br>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:</br></br>2258.misc</br></br>Inside the file I'll put a one-line description, something like:</br></br>Correct the header doc and soil-velocity parameter name in DepthDependentLinearDiffuser.</br></br>'''Run the tests locally'''<br></br>(See: https://landlab.csdms.io/install/developer_install.html#install)</br></br>From the main Landlab folder:</br>* Lint: nox -s lint (runs the linters to make sure code is clean and consistent)</br>* News frag: nox -s towncrier (checks to make sure there's a valid news frag)</br>* Code: nox -s test (this one takes a few minutes)</br>* Jupyter notebooks: nox -s test-notebooks (also takes a bit of time)</br>* Docs: nox -s build-docs (if you've changed any documentation, including inline)</br>Once all your tests are passing locally, you are ready to push to your remote fork.</br></br>'''Push to your remote fork'''<br></br>Once you've made and committed your changes with git, and the tests are all passing locally, push your changes to your remote fork.</br></br>Example:</br></br>git push origin gt/update-ddepdiff-init</br></br>'''Activate a Pull Request'''<br></br>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".</br></br>Press this button to activate a pull request for your changes.</br></br>This takes you to the main Landlab repository page on GitHub. Here you can:</br>* Give your Pull Request a title</br>* Describe your Pull Request</br>* Change it to a DRAFT Pull Request (using the arrow on the green Create Pull Request button)</br>Once you've done those steps, click the green '''Draft pull request''' button. This will activate a series of automated tests.</br></br>'''What Makes a Good Pull Request'''<br></br>* '''Small and focused''': Address one issue or feature per pull request. Avoid bundling multiple unrelated changes.</br>* '''Clear purpose''': The pull request should explain why a change is needed, not just what was changed.</br>* '''Draft first''': Open your pull request in '''draft mode''' so others can follow progress and provide early feedback.</br>* '''Readable history''': Prefer a clean commit history. Consider squashing or rebasing before final review.</br>* '''Well-tested and documented''': All code changes should be accompanied by appropriate tests and updated documentation.</br></br>'''Requesting a review'''<br></br>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!</br></br>A good way to do this add a Comment (see bottom of your Pull Request page), in which you request a review(s).</br></br>If you're not sure who should review it, just write something like: "Could someone at CSDMS review this please?"</br></br>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:</br></br>"Could @mcflugen, @mdpiper, and/or @gantian127 review this for me please?"</br></br>You can also request reviews from other community members - we highly encourage this!</br></br>'''How many reviews?'''<br></br>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.</br></br>'''The review dance'''<br></br>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!</br></br>'''The final step'''<br></br>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.</br></br>Time to celebration: your contribution is now official!ewer) will click the magic button that merges your PR into the main development version.
Time to celebration: your contribution is now official!
gtucker@colorado.edu +
CSDMS 2025 Webinars +
CSDMS IF +
Tucker +
Webinar +
Colorado +
From issue to pull request: how to contribute to CSDMS' open-source community code repositories +
10:00:00, 9 October 2025 +
https://cuboulder.zoom.us/meeting/register/xAgW3wQ-SjyR3N2VYvPAuQ +
YuFhdzVZUFI +
United States +
Creation date"Creation date" is a predefined property that corresponds to the date of the first revision of a subject and is provided by <a target="_blank" rel="nofollow noreferrer noopener" class="external text" href="https://www.semantic-mediawiki.org/wiki/Help:Special_properties">Semantic MediaWiki</a>.
13:25:44, 8 September 2025 +
Has query"Has query" is a predefined property that represents meta information (in form of a <a target="_blank" rel="nofollow noreferrer noopener" class="external text" href="https://www.semantic-mediawiki.org/wiki/Subobject">subobject</a>) about individual queries and is provided by <a target="_blank" rel="nofollow noreferrer noopener" class="external text" href="https://www.semantic-mediawiki.org/wiki/Help:Special_properties">Semantic MediaWiki</a>.
Last editor is"Last editor is" is a predefined property that contains the page name of the user who created the last revision and is provided by <a target="_blank" rel="nofollow noreferrer noopener" class="external text" href="https://www.semantic-mediawiki.org/wiki/Help:Special_properties">Semantic MediaWiki</a>.
Modification date"Modification date" is a predefined property that corresponds to the date of the last modification of a subject and is provided by <a target="_blank" rel="nofollow noreferrer noopener" class="external text" href="https://www.semantic-mediawiki.org/wiki/Help:Special_properties">Semantic MediaWiki</a>.
02:05:35, 15 October 2025 +
Terrestrial Working Group +, Coastal Working Group +, Marine Working Group +, Education and Knowledge Transfer (EKT) Working Group +, Cyberinformatics and Numerics Working Group +, Hydrology Focus Research Group +, Chesapeake Focus Research Group +, Critical Zone Focus Research Group +, Human Dimensions Focus Research Group +, Geodynamics Focus Research Group +, Ecosystem Dynamics Focus Research Group +, Coastal Vulnerability Initiative +, Continental Margin Initiative +, Artificial Intelligence & Machine Learning Initiative +, Modeling Platform Interoperability Initiative + and River Network Modeling Initiative +
