Skip to content

Latest commit

 

History

History
150 lines (109 loc) · 8.42 KB

CONTRIBUTING.md

File metadata and controls

150 lines (109 loc) · 8.42 KB
Raw

Contribution guidance

Modelled/Copied after the IOOS methodology this page documents the procedures for:

  1. Requesting new notebooks to be added to the EcoFOCI CodeLab;
  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:

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 jupyterbook/content/code_gallery directory of this repository.
      1. There are three directories where notebooks can be placed:
        1. data_access_notebooks -
        2. data_analysis_and_visualization_notebooks -
        3. data_management_notebooks -
    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 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/shaunwbell/notebooks_demos/actions
  3. Once the workflows are complete, check the EcoFOCI 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. ecofoci mailing list

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 EcoFOCI Data Demo Center Project Board

The project board captures the current progress on notebooks and adjustments to the EcoFOCI 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/ioos_code_lab.git

Set the upstream branch to the ioos/notebooks_demos repository:

$ git remote add upstream https://github.com/shaunwbell/ecofoci_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