Guide for Editors-in-chief¶

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.

Notebook Repository¶

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 transfer the notebook repository to the Environmental Data Science book organisation.

The notebook in the transferred repository 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

## Set up Quay.io credentials
- [ ] Set `QUAY_PASSWORD` and `QUAYUSERNAME` keys and values in the repository secrets (go to to the repository settings, left panel > Secret and variables > Actions)

## Filename and README
- [ ] Create and checkout a new branch `preparation`
- [ ] Commit and push the following changes:
  - [ ] Rename the filename of the template to the pattern (XXX-YYY-ZZZ, where XXX refers to the environmental system, YYY to the theme and ZZZ to a preferred identifier of the model, sensor or pre/post-processing pipeline). 
    For example, "forest-modelling-treecrown.ipynb"
  - [ ] Fill `notebook_name` and `quay_image` keys in the `config.json` file
  - [ ] Copy README template ([python](eic-readme-python.md), R, Julia) and replace the fields in the following lines:
    - [ ] replace `[repository name]` in 
      - [ ] L16, `<a href="https://github.com/eds-book-gallery/[repository name]/blob/main/LICENSE">`
      - [ ] L19, `<a href="https://notebooks.gesis.org/binder/v2/gh/eds-book-gallery/[repository name]/main?labpath=[repository name].ipynb">`
      - [ ] L22, `<a href="https://github.com/eds-book-gallery/[repository name]/actions/workflows/publish.yml/badge.svg">`
      - [ ] L23, `<img alt="Continuous integration badge" src="https://github.com/eds-book-gallery/[repository name]/actions/workflows/publish.yml/badge.svg">`
      - [ ] L49, `git clone https://github.com/eds-book-gallery/[repository name].git`
      - [ ] L54, `cd [repository name]`
      - [ ] L60, `conda activate [repository name]`
    - [ ] replace `[rohub_w3id]` in L29
- [ ] Merge the new branch to main

Pre-review¶

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

Copy and paste the markdown below in the issue:

Note

The PRE-REVIEW template follows the Journal of Open Source Education’s pre-review issue template

# Notebook Pre-Review

**Submitting author:** [AUTHOR GITHUB HANDLE]

**Repository:** [NOTEBOOK REPOSITORY LINK]

**Notebook idea issue:** [NOTEBOOK IDEA ISSUE ID]

**Editor:** Pending

**Reviewer:** Pending

**Managing EiC:** [EIC GITHUB HANDLE]

## Status

**Author instructions**

Thanks for submitting your notebook to EDS book. 

[AUTHOR GITHUB HANDLE] if you have any suggestions for potential reviewers then please mention them here in this thread (without tagging them with an @).

**Editor instructions**

Thank you for considering managing the review workflow of a notebook submission to EDS book.

Please find and assign reviewers and start the main review.

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

Important

The assigned editor should confirm acceptance and availability within 1 week.

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. EiC open it and replace the default first comment the markdown template below:

Note

The REVIEW template follows the Journal of Open Source Education’s review issue and checklist template

# Notebook Review: Issue#[PREREVIEW ID]

<p align="left">
    <a href="https://notebooks.gesis.org/binder/v2/gh/eds-book-gallery/[NOTEBOOK NAME]/review?labpath=[NOTEBOOK NAME].ipynb">
        <img alt="Binder" src="https://mybinder.org/badge_logo.svg">
    </a>
</p>

**Submitting author:** [AUTHOR GITHUB HANDLE]

**Repository:** [NOTEBOOK REPOSITORY LINK]

**Notebook idea issue:** [NOTEBOOK IDEA ISSUE ID]

**Editor:** [EDITOR GITHUB HANDLE]

**Reviewer:** [REVIEWER1 GITHUB HANDLE], [REVIEWER2 GITHUB HANDLE]

**Managing EiC:** [EIC GITHUB HANDLE]

## Status

**Reviewer instructions & questions**

Hi 👋 [REVIEWER1 GITHUB HANDLE] & [REVIEWER2 GITHUB HANDLE], please carry out your review in this issue by updating the checklist below. 

As a reviewer, you contribute to the technical quality of the content published by our community. 

Before the review, EiC checked if the submission fits the minimum requirements. 

The quality of the proposed contribution can be assessed through scientific, technical and code criteria. 

The reviewer guidelines are available here: <change-URL>. 
Any questions/concerns please let [EDITOR GITHUB HANDLE] know.

## Review Checklist for [REVIEWER GITHUB HANDLE]

```{include} ../../templates/reviewers/reviewers-review-checklist.md

To facilitate the discussion, EiC creates a new branch review to add reviewers info (name, affiliation, GitHub handle) in the contribution section of the notebook. 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).

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.

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.

Environmental Data Science Book

Guide for Editors-in-chief

Contents