CONTRIBUTING.md

Contribution guidance

This page documents the procedures for:

1. Requesting new notebooks to be added to the IOOS CodeLab;
2. Building new notebooks;
3. Reviewing submitted notebooks;
4. Merging approved notebooks for inclusion into the CodeLab;
5. Announcing the new notebooks to the community; and
6. Logging any bugs that are found in the CodeLab.
7. Managing the IOOS CodeLab Project Board.
8. Local management of the ioos_code_lab repository.

Requesting new notebooks

• New notebooks should be requested by adding an issue to this GitHub repository using this template. The ticket should contain the following information (also provided in the issue template):

- [ ] What is language(s) for used in the example?
- [ ] Is it focused on a particular module/software or an IOOS data service?
- [ ] Can you provide a minimum example of the expected code and results in a notebook?

Please provide a detailed description of the suggested example below:

For the admin

When the ticket gets created, make the following additions to the ticket:

• Add the label Notebook idea.
• Add the ticket to the IOOS CodeLab project.
• Put the card in the column backlog.

Building new notebooks

If you would like to work on a notebook that has been proposed, follow these steps:

1. Create a fork of the ioos_code_lab repository.
2. On your fork, create a branch where you will start working on the new notebook.
   1. Give the branch a name that conveys what the new notebook is. For example, a notebook on converting data into Darwin Core could have a branch name of data2dwc. This makes it easier to know which branch is dedicated to which new notebook.
3. On the new branch in your fork, start creating the new notebook.
   1. Notebooks are kept in the jupyterbook/content/code_gallery directory of this repository.
      1. There are three directories where notebooks can be placed:
         1. data_access_notebooks - Notebooks exemplifying how to access data from various services using various tools.
         2. data_analysis_and_visualization_notebooks - Notebooks exemplifying doing some analysis and/or visualizations using tools common in the IOOS community.
         3. data_management_notebooks - Notebooks on how to use various tools to ensure compliance with existing standards and conventions.
   2. Typically, it's best to copy an existing (working) notebook to a new file. If you are creating a python notebook, copy one of the python notebooks. If you are creating an R notebook, copy one of the R notebooks, etc
   3. Name the notebook following the convention [date]-[short name].ipynb. Where, [date] is the date (YYYY-MM-DD) you started the new notebook and [short name] is an abbreviation for what the notebook will cover. Look at the existing notebook filenames to get a sense of the short names used.
4. Edit the notebook following the Jupyter Notebook documentation. The notebook should include the following information:
   1. Descriptive title for what the notebook is doing.
   2. A short summary providing context and expanding on the title.
   3. The date you started (or updated) the notebook.
5. Once you feel comfortable with your notebook, commit your work to the branch on your fork on your local machine.
6. Push your commit up to the branch on your fork in GitHub.
7. Create a Pull Request (PR).
8. Link the PR to the ticket requesting the new notebook.
   1. On the right hand side of the PR there is an option for Linked issues. Type the number for the issue there (or scroll through the tickets until you find the one of interest).
   2. Admin Move the Project card from Backlog to Working.
9. When you are ready for it to be merged, in the PR click Ready for review.
   1. Admin Move the Project card from Working to Needs Review.

Reviewing

See pull request reviews for more information on reviewing PRs.

Each new notebook needs at least one reviewer.

1. When the PR is Ready for review, the reviewer should:
   1. Try running the entire notebook. Typically by selecting from the Kernel dropdown Restart and Run All.
      1. Any errors here should be logged and fixed or reported back to the PR. Admin move the Project card from Needs Review to Working.
   2. Review the notebook for understandability.
      1. Does the notebook clearly describe the processes happening in each cell? Does it provide context?
   3. Review the code to ensure it's doing what it's supposed to.
   4. Check for spelling errors.

Merging

For Administrators:

1. If the notebook looks good, the reviewer will merge the PR.
2. This kicks off a series of GitHub Actions.
   1. You can see the workflows at https://github.com/ioos/ioos_code_lab/actions
3. Once the workflows are complete, check the IOOS CodeLab for the new notebook.
4. Review the notebook for any display issues when presented on the web. Check for the extra cell at the bottom of the notebook.
   1. If there are issues, submit a new PR to resolve the issues.

Announcing

When new notebooks, or significant changes to the site, are merged and pushed out, follow this procedure:

1. Admin Move the appropriate Project card to Announcement.
2. Draft announcement text.
   1. Include a brief summary of the new release.
   2. Include any relevant links to the demo center.
3. Distribute text through the following channels.
   1. IOOS bi-weekly
   2. EOTO
   3. ioos_tech mail list
   4. dmac mail list
   5. Twitter/FB.
   6. Appropriate slack channels

Logging bugs or changes

1. Bugs should be reported through tickets in this repository. Be sure to include the notebook where the problem is found. Include a clear description of the issue or change that is needed.

Managing IOOS Data Demo Center Project Board

The project board captures the current progress on notebooks and adjustments to the IOOS Data Demo Center.

Column name	Purpose
Icebox	Back burner tickets to keep in the fray.
Backlog	Tickets to be worked on next.
Working	Tickets actively being contributed to.
Needs Review	Tickets where a PR has been requested to merge.
Announcement	Tickets that have been merged and an announcement needs to be made.
Done	All completed tickets.

Local management of ioos_code_lab

This section walks through one way to manage the notebooks_demo git repository on your local machine.

Clone your fork of the notebooks_demo repository to a known location on your machine:

$ git clone https://github.com/MathewBiddle/ioos_code_lab.git

Set the upstream branch to the ioos/ioos_code_lab repository:

$ git remote add upstream https://github.com/ioos/ioos_code_lab.git

Keep your local main up-to-date with the upstream main (walkthough):

$ git fetch upstream
$ git pull upstream/main main

OR

$ git merge upstream/main main

Rebase (if needed):

$ git rebase upstream/main

Push your local repo up to your fork in GitHub.

$ git push