diff --git a/README.md b/README.md index cd05bb9..1f2e1e7 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,61 @@ -### ReScience C published articles +## Publishing a ReScience C article -In order to publish a new article (after acceptance), you'll need to have the -article metadata file (YAML format) and the corresponding article (PDF -format). The metadata file should be missing the article DOI, number and -URL. The first step is thus to request this information from Zenodo. Before +This document is intended for ReScience editors. Congrats on accepting a ReScience article for publication! If you're new at editing, this document will guide you through all the necessary steps. If you are a seasoned editor, this will be a handy reference to any steps you may have forgotten. Follow the steps below to complete the metadata, submit to Zenodo, and get the final article published. + +### What you will need to begin +- The article metadata file (`metadata.yaml`) from the author's repository. At this time the metadata file **will be missing** the article DOI, number and URL. This is expected and something you will fix over the coming steps. +- The near final article itself (`article.pdf`) + +Have these two files ready before cloning this repository. This would also be a good time to ask reviewers to share their [ORCIDs](https://orcid.org/) for the metadata. You can do this in the review issue. + +### Publishing the article + +There are 5 parts to publishing the article. + +| Part | What it does | +|:--|:--| +| [Set up credentials](#set-up-credentials) | Get setup to programmatically submit to Zenodo | +| [Pre-publish the paper](#pre-publish-the-paper) | Reserve the DOI | +| [Update the metadata](#update-the-metadata) | Add volume, issue, page, doi to the paper & generate new pdf | +| [Publish the paper](#publish-the-paper) | Make the final Zenodo deposit | +| [Update the website](#website-update) | Enter bib information for the website | + + + +### 14 steps to publishing a ReScience article + +1\. Clone this repository locally. +2\. Copy the authors `metadata.yaml` and `article.pdf` into this folder + +### Set up Credentials + +3\. To submit the paper and metadata to Zenodo, you will need to set up access tokens. Setting up your Zenodo sandbox and production tokens is a one time step. If you have done this before, skip over to step 4. + +The first step is thus to request this information from Zenodo. Before proceeding further, you'll need a Zenodo token that can be requested from the [sandbox server](https://sandbox.zenodo.org/account/settings/applications/tokens/new/) and from the [actual -server](https://zenodo.org/account/settings/applications/tokens/new/). - +server](https://zenodo.org/account/settings/applications/tokens/new/). When creating tokens, be sure to check all three scopes. The sandbox token is expected to be stored in the environment variable `ZENODO_SANDBOX_TOKEN` while the true token must be stored in `ZENODO_TOKEN`, e.g.: ```bash export ZENODO_SANDBOX_TOKEN="access token" +export ZENODO_TOKEN="access token" ``` And to check it was set correctly: ```bash echo $ZENODO_SANDBOX_TOKEN +echo $ZENODO_TOKEN ``` -We strongly advise you to **first test the procedure** on the sandbox server -using the `--sandbox` switch. +If you copy these into your bash profile you won't have to look for them again. We advise you to **first test the procedure** on the sandbox server using the `--sandbox` switch. More on this in the next step. + +### Pre-publish the paper -#### 1. Pre-Publication (article DOI, URL and number) +This step reserves the DOI for the paper, allowing you to update metadata before final publication. -Run the [process.py](process.py) script using the provided metadata +4\. Run the [process.py](process.py) script using the provided metadata file. It requires Python 3 plus the libraries [PyYAML](https://pyyaml.org/), [Requests](https://requests.kennethreitz.org/), and [dateutil](https://dateutil.readthedocs.io/en/stable/). First run on the sandbox server to check everything is OK: @@ -37,8 +67,7 @@ Article DOI: 10.xxxx/zenodo.xxxxx Article URL: https://sandbox.zenodo.org/record/xxxxxx/file/article.pdf ``` -Then use the actual server using the `--zenodo` switch instead of the -`--sandbox` switch. +5\. Did this work? Were there any problems? If there were no problems, then use the production server using the `--zenodo` switch instead of the `--sandbox` switch. ```bash $ ./process.py --zenodo --metadata metadata.yaml --pdf article.pdf @@ -47,48 +76,37 @@ Article DOI: 10.xxxx/zenodo.xxxxx Article URL: https://zenodo.org/record/xxxxxx/file/article.pdf ``` -You must also assign the issue, volume, and article numbers. Have a -look on the published articles and assign the next available number in -the same issue and same volume if your article is still in the same -year. Otherwise, increment the volume number and start with -issue 1. The issue number is only changed for accommodating special issues. -Post your numbers to [this GitHub issue](https://github.com/ReScience/ReScience/issues/48) -that serves to avoid that two editors assign the same numbers to two -different articles. +6\. If no errors were returned, you have successfully reserved a DOI! Next we’ll grab an issue, volume and article numbers. + +``` +NOTE: This DOI will not resolve anywhere. This behavior is expected +``` +### Update the metadata -#### 2. Metadata update and creation of the final PDF +In this step, you'll update `metadata.yaml`, pull request the file back to the author, generate a new PDF (which will now contain the volume, issue, page, doi information), and copy that back here. -The `metadata.yaml` has a section (at the end) for information added during -the publication process. You should complete it and verify the whole file -before moving on. The information you must add is: +7\. Look at the last number on [this GitHub issue](https://github.com/ReScience/ReScience/issues/48) and choose the next one in the series. Post a comment to claim that issue for your article. This comment +serves to avoid that two editors assign the same numbers to two +different articles. + +8\. Then add these two bits of information (volume and article number) along with the Zenodo DOI and URL to `metadata.yaml`. + +You should complete the missing information and verify the whole file before moving on. The information you must add are: - DOI (from Zenodo) - article URL (from Zenodo) - contributors (reviewers and editors), with ORCIDs - acceptance and publication date - issue, volume, and article numbers. -Next, there are two situations: - - - If the authors have used the [ReScience article template](http://github.com/rescience/template), - you can fork their repository, copy the edited `metadata.yaml` to it, and create - the final PDF by running `make`. Don't forget to submit a pull request to the - authors' repository with the changes you made to `metadata.yaml`. - - - Otherwise, you give the authors the required information and - ask them to update their article and produce the final PDF file. You should - check that their PDF contains all the information you sent them. +9\. Pull request just the `metadata.yaml` back to the author's repo (this will mean copying this file back to the author repo fork). Once the pull-request is merged, ask them to prepare a new `article.pdf`. The PDF will now contain the volume, article number and DOI. -You need to give this information back to author(s) such that they can update -the metadata file as well as the article that display the DOI in the left -margin (make sure they actually update this information). For the article -number, you can have a look on the published articles and assign the next -available number in the same issue and same volume. +10\. Copy the newly updated `article.pdf` and `metadata.yaml` back to this repo. + +### Publish the paper -#### 3. Publication (Zenodo and GitHub) - -In order to publish the **final** article, you'll need to run the +11\. In order to publish the **final** article, you'll need to run the [publish.py](publish.py) script: ```bash @@ -113,19 +131,26 @@ A new git branch (10.5072_zenodo.xxxxx) has been created. ``` This example uses the sandbox, replace `--sandbox` by `--zenodo` for -publishing to the Zenodo production site! This will create a new -public record on Zenodo and also create a new local directory -corresponding to the entry. This means you need to push this new -branch on GitHub and make a pull request (the commit will have been -created automatically). - - -#### Website update - -To have the new article to appear on the website, you'll need to prepend the -newly created bibtex entry (look into the local repository) to the -[published.bib](https://github.com/ReScience/rescience.github.io/blob/sources/_bibliography/published.bib) -file on the website (you can do it directly from the GitHub interface). If you -previously added the entry to the -[under_review.bib](https://github.com/ReScience/rescience.github.io/blob/sources/_bibliography/under-review.bib) -file, don't forget to remove it. +publishing to the Zenodo production site. + +This will create a new folder and branch in `Rescience/articles` named after the article's DOI that contains three files: + - The article (`article.pdf`) + - metadata (`article.yaml`) + - bib file (`article.bib`) + +- Now push this branch: + +``` +git push origin +``` + + +12\. Discard any changes on the master branch. + +### Website update + +To have the new article to appear on the website, you'll need to prepend the newly created bibtex entry. + +13\. Finally, copy the contents of `article.bib` from the doi folder for this paper into [rescience.github.io/_bibliography/published.bib](https://github.com/ReScience/rescience.github.io/blob/sources/_bibliography/published.bib) and send a final pull request (You can do this from the web). + +14\. Now you’re done! 🎉 🚀