Skip to article frontmatterSkip to article content

Welcome to the guide for notebooks EiC of the EDS book!

Before you begin this process, please be sure to understand how the publication process works.

We have a code of conduct which is mandatory for everyone involved in the review process of our notebooks.

Below you will find the main steps we suggest to follow to moderate, validate and publish a notebook to EDS book.

Scope and Aims

Thank you for considering leading the publication process of a notebook to EDS book. Our review process aims to be open, collaborative, transparent and inclusive.

Notebook Idea

In this step, we suggest providing feedback to the notebook idea.

Preparation

EiC validate how reproducible is the notebook and its feasibility for the reviewing stage. This process is aided by the Binder badge in a PR in the corresponding author’s notebook repository.

After validating a minimal working version, EiC fork the notebook repository to the Environmental Data Science book organisation.

The forked notebook should generate the same outputs as the initial repository hosted in the GitHub account of the corresponding author.

Before moving to PRE-REVIEW, EiC open a new issue Preparation in the notebook repository and complete the checklist below:

# Check notebook repository
- [ ] The notebook repository is available in a public personal repository
- [ ] The notebook runs in Binder according to the PR indicated by the author

# Initial configurations
- [ ] Create and checkout a new branch `preparation`
- [ ] Activate the conda environment containing Jupyter Book v2 and run `jupyter book init` to create myst.yml file.
- [ ] Move environment.yml file to `.binder` folder
- [ ] Rename the `name` field in `.binder/environment.yml` with project id defined in `myst.yml` file

# Set up Quay.io
- [ ] Create a new Quay.io repository with the same name as the project id defined in `myst.yml` file and another including the suffix `_preview` (e.g., `my-project-id` and `my-project_preview-id`)
- [ ] Assign in settings the `edsbook+github_actions` bot as a collaborator with write access to the Quay.io repository

# GitHub repository settings
- [ ] Set `QUAY_PASSWORD` and `QUAYUSERNAME` keys and values from the bot in the repository secrets (go to the repository settings, left panel > Secret and variables > Actions)
- [ ] Check that the GitHub pages are enabled in the repository settings using actions.

# README (python)
- [ ] Rename the filename of the template to notebook.ipynb
- [ ] Copy README template (python) and replace the fields in the following lines:
- [ ] replace `[repository name]` in 
  - [ ] L20, `git clone https://github.com/eds-book/[repository name].git`
  - [ ] L25, `cd [repository name]`
  - [ ] L31, `conda activate [repository name]`
    
# Validate preview
- [ ] Commit and push changes to the `preparation` branch
- [ ] Open a PR to the `main` branch with the title `preparation` and the description
- [ ] Check the publish action in the Actions tab runs successfully
- [ ] Validate the preview in GitHub pages at `https://eds-book.github.io/[repository name]/`
- [ ] If OK, merge the PR to the `main` branch.

The myst.yml file should be created in the root of the notebook repository, and some fields should be filled.

    # See docs at: https://mystmd.org/guide/frontmatter
    version: 1
    extends:
       - https://raw.githubusercontent.com/eds-book/edsbook-config/main/edsbook.yml
    project:
      id: [KEEP-THE-ORIGINAL-ID]
      title: [NOTEBOOK-TITLE] (Jupyter Notebook) published in the Environmental Data Science book
      short_title: [NOTEBOOK-SHORT-TITLE]
      abstract: Notebook developed to [SHORT-ABSTRACT].
      authors:
        - id: [SHORT-ID]
          name: [FIRST-AND-LAST-NAME]
          orcid: [ORCID]
          corresponding: true
          email: [EMAIL]
          github: [GITHUB-HANDLE]
          roles:
            - Investigation
            - Software
            - Visualization
          affiliations:
            - [ID-AFFILIATION]
    #  reviewers:
    #    - id: TBA
    #      name: TBA
    #      orcid: TBA
    #      github: TBA
    #      roles:
    #        - Writing – review & editing
    #      affiliations:
    #        - TBA
    #  editors:
    #    - id: TBA
    #      name: TBA
    #      orcid: TBA
    #      github: TBA
    #      roles:
    #        - Writing – review & editing
    #      affiliations:
    #        - TBA
      affiliations:
        - id: [ID-AFFILIATION]
          name: [AFFILIATION-NAME]
          department: [AFFILIATION-DEPARTMENT]
      subject: [SUBJECT] #according to Earth Engine Data Catalog categories, https://developers.google.com/earth-engine/datasets/categories
      keywords:
        - [SUBJECT]
        - [THEME]
        - [SUBMISSION]
        - [LANGUAGE]
      venue:
        title: Environmental Data Science Book
        short_title: EDS Book
        url: https://www.edsbook.org
      issue:
        name: [SUBMISSION-TYPE]
    #  thumbnail: images/thumbnail.png
      requirements:
        - .binder/environment.yml
      #doi: 10.5281/zenodo.XXXXXXX
      github: https://github.com/eds-book/[KEEP-THE-ORIGINAL-ID]
      jupyter:
        binder:
          repo: eds-book/[KEEP-THE-ORIGINAL-ID]
      open_access: true
      license:
        content: CC-BY-4.0
        code: MIT
      date: YYYY-MM-DD
      toc:
        - file: README.md
        - file: notebook.ipynb
    site:
      template: book-theme

Pre-review

EiC open a PRE-REVIEW issue containing all relevant information of the notebook including a link to the notebook idea issue.

- [ ] Open a PRE-REVIEW issue
- [ ] Fill the required fields.
- [ ] Provide details of the notebook using [cloc](https://github.com/AlDanial/cloc).
- [ ] Notify about the PRE-REVIEW issue to the author in the notebook idea issue.
- [ ] Validate reviewers interest and availability
- [ ] Close the PRE-REVIEW

EiC assign an editor to moderate the review and find reviewers.

After the editor acceptance, EiC will update the heading at the top of the issue with [EDITOR GITHUB HANDLE] next to Editor: section. Once reviewers agreed on the revision, EiC open a REVIEW issue.

Review

The REVIEW issue aims to be a space where editor will moderate timings and conversation between authors and reviewers.

- [ ] Create and checkout a new branch `review`
- [ ] Add a custom message in the first markdown cell of the notebook after the title indicating "Authors and Reviewers. This is the notebook version for review. We will remove this markdown cell after the peer-review."
- [ ] Commit and push changes to the `review` branch
- [ ] Open a REVIEW issue
- [ ] Fill the required fields   
- [ ] Add reviewers
- [ ] Provide details of the notebook using [cloc](https://github.com/AlDanial/cloc).
- [ ] Moderate the discussion between authors and reviewers
- [ ] Check suggested changes by reviewers are implemented in the notebook repository
- [ ] If changes are implemented, merge the PR to the `main` branch

To facilitate the discussion, EiC creates a new branch review with a custom message at the first markdown cell indicating “Authors and Reviewers. This is the notebook version for review. We will remove this markdown cell after the peer-review.” Then EiC commit and push changes to create a PR in the notebook repository. The PR will trigger ReviewNB, a third-party plugin in GitHub for displaying and commenting Jupyter Notebooks (see further details here). EiC should reminder the authors to implement changes in their personal repository and not in the forked repository. The authors should open a PR to the forked repository to update the notebook version for review. EiC merges the PR in the review branch and suggest to the editor to ask the reviewers to re-evaluate the notebook.

Once reviewers recommend the notebook for publication, EiC will be notified by the editor to start the post-print stage.

Post-print

EiC will lead publishing asking authors to proof-read the notebook and indicate any remaining typos, badly formed citations, awkward wording, etc.

# Initial configurations
- [ ] Create and checkout a new branch `postprint`
- [ ] Remove files in the `images` folder
- [ ] Create and add `thumbnail.png` to the `images` folder
- [ ] Set `.bumpversion.cfg`

# Archive in Zenodo
- [ ] Create a Zenodo record for the notebook repository
- [ ] Use the nomenclature of the .bumpversion.cfg file to set the version number

# Notebook 
- [ ] Add `Citing this Notebook` section to the notebook before the `Additional Information` section. 
    ```markdown
    ## Citing this Notebook
    
    Please see [CITATION.cff](https://github.com/eds-book/[repository-name]/blob/main/CITATION.cff) for the full citation information. The citation file can be exported to APA or BibTex formats (learn more [here](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files)).
    ```

# myst.yml file
- Complete missing fields in the `myst.yml` file:
    ```yaml
    project:
      reviewers:
        - id: TBA
          name: TBA
          orcid: TBA
          github: TBA
          roles:
            - Writing – review & editing
          affiliations:
            - TBA
      editors:
        - id: TBA
          name: TBA
          orcid: TBA
          github: TBA
          roles:
            - Writing – review & editing
          affiliations:
            - TBA
       thumbnail: images/thumbnail.png
       doi: 10.5281/zenodo.XXXXXXX
       date: YYYY-MM-DD
       exports:
        - format: cff
          version: [version]
          identifiers:
            - description: "Open review report for this notebook"
              type: url
              value: "https://github.com/eds-book/notebooks-reviews/issues/[review-issue]"
       bibliography:
        - references.bib
    ```
  
- Change the version in the cell `print('Notebook repository version: [version]')`

# README 
- [ ] Between the title and how to run sections, add the following lines replacing `[repository-name]`, `[zenodo-doi]`, `[zenodo-badge]` and `[review-issue]` in:
    ```markdown
    <p align="center">
        <a href="https://github.com/eds-book/[repository name]/actions/workflows/monthly-build.yaml/badge.svg">
            <img alt="Continuous integration badge" src="https://github.com/eds-book/[repository name]/actions/workflows/monthly-build.yaml/badge.svg">
        </a>
        <a href="http://mybinder.org/v2/gh/eds-book/[repository name]/main?labpath=notebook.ipynb">
            <img alt="Binder" src="https://mybinder.org/badge_logo.svg">
        </a>
        <a href="https://doi.org/10.5281/zenodo.[zenodo-doi]">
            <img alt="doi" src="https://zenodo.org/badge/[zenodo-badge].svg">
        </a>
        <a href="https://github.com/eds-book/notebooks-reviews/issues/[review-issue]">
            <img alt="notebook review" src="https://img.shields.io/badge/view-review-purple">
        </a>
    </p>
    
    <p align="center">
    <img src="images/thumbnail.png" alt="thumbnail" width="500"/>
    </p>
    ```

# Validate preview
- [ ] Commit and push changes to the `postprint` branch
- [ ] Open a PR to the `main` branch with the title `postprint` and the description
- [ ] Check the publish action in the Actions tab runs successfully
- [ ] Validate the preview in GitHub pages at `https://eds-book.github.io/[repository name]/`
- [ ] If OK, merge the PR to the `main` branch.

Publication

EiC will announce the notebook in the EDS book social accounts and tag authors accounts according to their authorization.

Post-publication

EDS book community and other practitioners in GitHub could suggest changes in the notebook. Where relevant, EiC will notify authors about proposed changes and their acceptance. If the authors consider suggestions as a substantial contribution, EiC will acknowledge it by adding the contributor’s name to the citation of the notebook.

Guidelines
Guide for Editors
Guidelines
Guide for Community