Skip to content

Home

Jump to bottom
Mathew Biddle edited this page Apr 1, 2021 · 11 revisions

Welcome to the notebooks_demos wiki!

This wiki page documents the procedures for:

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

Requesting new notebooks

  • New notebooks should be requested by adding a ticket to this GitHub repository. The ticket should contain the following information:
- [ ] 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:

See this example ticket for reference.

For the admin

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

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 notebooks_demos 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 notebooks_demo/notebooks directory of this repository.
    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 DRAFT-[short name].ipynb. Where, [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.
  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 Draft Pull Request (PR).
    1. This is the same as creating a PR, you just use the drop-down and select Create Draft Pull Request, then click Draft Pull Request.
  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 Admins:

  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/notebooks_demos/actions
  3. Once the workflows are complete, check the code gallery 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 notebooks_demo

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/notebooks_demos.git

Set the upstream branch to the ioos/notebooks_demos repository:

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

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

$ git fetch upstream
$ git pull upstream/master master

OR

$ git merge upstream/master master

Rebase (if needed):

$ git rebase upstream/master

Push your local repo up to your fork in GitHub.

$ git push
Clone this wiki locally