GitHub - pyOpenSci/software-peer-review: pyOpenSci's guidebook for package authors, reviewers, and editors (original) (raw)
pyOpenSci Peer Review Guide
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:
- Create a fork of this repo to make changes.
- 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)
- When satisfied, push the changes back to GitHub and open a pull request from your fork to the main branch of this repo.
- 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).
- The reviewer of the PR may request modifications.
- 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:
- Install
nox - Build the documentation:
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:
- 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.
Contributors ✨
Thanks goes to these wonderful people (emoji key):
Tom Augspurger
Ariane Sasso
Ryan Abernathey
David Nicholson
Stefan van der Walt
Erik Welch
Alex Batisse
Chiara Marmo
Yuvi Panda
Niels Bantilan
Carol Willing
Chris Holdgraf
Steve Moss
Ivan Ogasawara
Kylen Solvik
Matthew Brett
Zehua Chen
Sumit Kashyap
Erik Sundell
Max Joseph
Ariel Rokem
James Mason
Juan Luis Cano Rodríguez
Mahe Iram Khan
Qin
David Stansby
P. L. Lim
Nick Murphy
Hans Moritz Günther
g-patlewicz
ruoxi
Gregor Sturm
Sean Kelly
Jesse Mostipak
Tobias Megies
C. Titus Brown
Bane Sullivan
Avik BasuThis project follows the all-contributors specification. Contributions of any kind welcome!