Skip to content

pyOpenSci/software-peer-review

Repository files navigation

pyOpenSci Peer Review Guide

All Contributors

GitHub release (latest by date) DOI deploy-book CircleCI

https://www.pyopensci.org/peer-review-guide/

pyOpenSci's guide for developing, reviewing, and maintaining packages.

Contributing to this guide

We welcome issues and pull requests to improve the content of this guide. If you'd like to see an improvement, please open an issue.

To submit a Pull Request with changes:

  1. Create a fork of this repo to make changes.
  2. After making changes, build the book locally from your fork to preview the changes to make sure they appear as expected (see How to build the guide locally below)
  3. When satisfied, push the changes back to GitHub and open a pull request from your fork to the main branch of this repo.
  4. The Continuous Integration processes will build the book and let you and the PR reviewer(s) preview it in your browser (see Automated build and publishing below).
  5. The reviewer of the PR may request modifications.
  6. Once satisfied, the reviewer will merge your pull request! Thanks for your contribution!

How to build the guide locally

The pyOpenSci guidebook is written using Jupyter Book.

To build the guide locally, take the following steps:

  • Clone this repository (or clone your fork by replacing "pyOpenSci" with your GitHub username):

    git clone https://github.com/pyOpenSci/peer-review-guide
    

To build, follow these steps:

  1. Install nox
pip install nox
  1. Build the documentation:
nox -s docs

This should create a local environment in a .nox folder, build the documentation (as specified in the noxfile.py configuration), and the output will be in _build/html.

To build live documentation that updates when you update local files, run the following command:

$ nox -s docs-live
  • To view your built book:

Navigate to _build/html/ on your local clone of the repo and open "index.html".

Automated build and publishing

Whenever a pull request is opened or changes are pushed to any branch of the base repository, the book is built (separately) by both GitHub Actions and CircleCI.

Why both GitHub Actions and CircleCI?

  • GitHub Actions is the main build tool. In addition to building whenever a pull request is opened from a fork, it handles publishing the book when changes are made to the main branch (e.g. once the pull request is merged). When that happens, it pushes the built html files to the gh-pages branch, which publishes the book to the website.
  • CircleCI's build is redundant, but it offers an easier way of viewing the built html in browser WITHOUT merging the changes to main or downloading files. See How do you preview the the guide from a Pull Request below for details.

How do you preview the guide from a Pull Request?

  • (Recommended) Via the artifact redirector workflow: When viewing the checks in a pull request, click "Details" next to the "Click to preview rendered book" to be automatically taken to the CircleCI index.html preview. This is performed using the circleci-artifacts-redirector-action workflow. See the gif below for a demonstration.
  • Via CircleCI: Go to the CircleCI job and select the "Artifacts" tab. Click on "index.html" to preview the built book.
  • Via GitHub Actions alone: GitHub Actions also saves the built html files for preview, but you have to download and unzip the files to your local computer. Go to your deploy-book build in the Actions tab. Then select "book-html" in the "Artifacts" pane near the bottom of the page. After downloading, unzip the book-html.zip file into a separate directory and open "index.html" from the directory with the unzipped files. The book should open in your web browser.

preview_book2

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Tom Augspurger
Tom Augspurger

πŸ’» πŸ‘€ 🎨
Ariane Sasso
Ariane Sasso

πŸ’» πŸ‘€ 🎨
Ryan Abernathey
Ryan Abernathey

πŸ’» 🎨 πŸ‘€
David Nicholson
David Nicholson

πŸ’» πŸ‘€ 🎨
Stefan van der Walt
Stefan van der Walt

πŸ’» πŸ‘€ 🎨
Erik Welch
Erik Welch

πŸ’» πŸ‘€ 🎨
Alex Batisse
Alex Batisse

πŸ’» πŸ‘€ 🎨
Chiara Marmo
Chiara Marmo

πŸ’» πŸ‘€ 🎨
Yuvi Panda
Yuvi Panda

πŸ’» 🎨 πŸ‘€
Niels Bantilan
Niels Bantilan

πŸ’» πŸ‘€
Carol Willing
Carol Willing

πŸ‘€ πŸ’»
Chris Holdgraf
Chris Holdgraf

πŸ‘€ πŸ’» 🎨
Steve Moss
Steve Moss

πŸ‘€ πŸ’»
Ivan Ogasawara
Ivan Ogasawara

πŸ‘€ πŸ’»
Kylen Solvik
Kylen Solvik

πŸ‘€ πŸ’» 🎨
Matthew Brett
Matthew Brett

πŸ‘€ πŸ’»
Zehua Chen
Zehua Chen

πŸ‘€ πŸ’»
Sumit Kashyap
Sumit Kashyap

πŸ’» πŸ‘€
Erik Sundell
Erik Sundell

πŸ‘€ πŸ’»
Max Joseph
Max Joseph

πŸ‘€ πŸ’»
Ariel Rokem
Ariel Rokem

πŸ‘€ πŸ’»
James Mason
James Mason

πŸ‘€ πŸ’»
Juan Luis Cano RodrΓ­guez
Juan Luis Cano RodrΓ­guez

πŸ’» πŸ‘€
Mahe Iram Khan
Mahe Iram Khan

πŸ’» πŸ‘€
Qin
Qin

πŸ’» πŸ‘€
David Stansby
David Stansby

πŸ’» πŸ‘€
P. L. Lim
P. L. Lim

πŸ’» πŸ‘€
Nick Murphy
Nick Murphy

πŸ’» πŸ‘€
Hans Moritz GΓΌnther
Hans Moritz GΓΌnther

πŸ’» πŸ‘€
g-patlewicz
g-patlewicz

πŸ’» πŸ‘€
ruoxi
ruoxi

πŸ’» πŸ‘€
Gregor Sturm
Gregor Sturm

πŸ’» πŸ‘€
Sean Kelly
Sean Kelly

πŸ’» πŸ‘€
Jesse Mostipak
Jesse Mostipak

πŸ’» πŸ‘€
Tobias Megies
Tobias Megies

πŸ’» πŸ‘€
C. Titus Brown
C. Titus Brown

πŸ’» πŸ‘€

This project follows the all-contributors specification. Contributions of any kind welcome!