Guide for Editors-in-chief

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 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

## 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 notebook.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=notebook.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
- [ ] Open a PRE-REVIEW issue
- [ ] Fill the required fields.  
- [ ] Validate reviewers interest and availability
- [ ] Close the PRE-REVIEW

## REVIEW
- [ ] Open a REVIEW issue
- [ ] Fill the required fields   
- [ ] Add reviewers
- [ ] Provide details of the notebook using [cloc](https://github.com/AlDanial/cloc).

Pre-review#

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

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.

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.

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.