From a5ad591260dabf84dde2f2d17c59419a0b7775f9 Mon Sep 17 00:00:00 2001 From: Karthik Ram Date: Mon, 3 Aug 2020 09:04:22 -0700 Subject: [PATCH 1/8] Updated readme based on discussion at #11 --- README.md | 141 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 83 insertions(+), 58 deletions(-) diff --git a/README.md b/README.md index cd05bb9..41effb6 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,59 @@ -### 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 +Congrats on accepting a ReScience article for publication! 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 should **will be missing** the article DOI, number and URL. This is expected and something you will fix over the coming steps. +- The final article itself (`article.pdf`) + +Have these two files ready before cloning this repository. + +### Publishing the article + +There are 5 parts to publishing the article. + +| Step | What it does | +|:--|:--| +| Set up credentials | Get setup to programmatically submit to Zenodo | +| Pre-publish the paper | Reserves the DOI | +| Update the metadata | Add volume, issue, page, doi to the paper & generate new pdf | +| Publish the paper | Make the final Zenodo deposit | +| Update the website | Enter bib information for the website | + + + +### 14 steps to publish 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 in your bash profile you wont 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 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/). @@ -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. +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 is: - 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, have them `Make` 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! 🎉 🚀 From 5f14389e40e05c32d43495863d327c8dc530741a Mon Sep 17 00:00:00 2001 From: Karthik Ram Date: Mon, 3 Aug 2020 10:55:13 -0700 Subject: [PATCH 2/8] Clarified audience and added links in toc --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 41effb6..a1228d4 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ ## Publishing a ReScience C article -Congrats on accepting a ReScience article for publication! Follow the steps below to complete the metadata, submit to Zenodo, and get the final article published. +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. 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 should **will be missing** the article DOI, number and URL. This is expected and something you will fix over the coming steps. @@ -14,11 +14,11 @@ There are 5 parts to publishing the article. | Step | What it does | |:--|:--| -| Set up credentials | Get setup to programmatically submit to Zenodo | -| Pre-publish the paper | Reserves the DOI | -| Update the metadata | Add volume, issue, page, doi to the paper & generate new pdf | -| Publish the paper | Make the final Zenodo deposit | -| Update the website | Enter bib information for the website | +| [Set up credentials](#set-up-credentials) | Get setup to programmatically submit to Zenodo | +| [Pre-publish the paper](#pre-publish-the-paper) | Reserves 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 | From 977098b428cbab71e5ebc332eff763cb673ae38d Mon Sep 17 00:00:00 2001 From: Karthik Ram Date: Mon, 3 Aug 2020 10:56:36 -0700 Subject: [PATCH 3/8] More clarification --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a1228d4..9a2a6e3 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ ## Publishing a ReScience C article -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. Follow the steps below to complete the metadata, submit to Zenodo, and get the final article published. +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 should **will be missing** the article DOI, number and URL. This is expected and something you will fix over the coming steps. From 67297bfd85541343251f52e8398f50f12040f531 Mon Sep 17 00:00:00 2001 From: Karthik Ram Date: Mon, 3 Aug 2020 10:58:16 -0700 Subject: [PATCH 4/8] Added missing bullets --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 9a2a6e3..4c85fa6 100644 --- a/README.md +++ b/README.md @@ -55,7 +55,7 @@ If you copy these in your bash profile you wont have to look for them again. We 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: @@ -67,7 +67,7 @@ Article DOI: 10.xxxx/zenodo.xxxxx Article URL: https://sandbox.zenodo.org/record/xxxxxx/file/article.pdf ``` -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. +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 From 5f37e5322f9dcdd6337acebebd96209a49c142ed Mon Sep 17 00:00:00 2001 From: Karthik Ram Date: Mon, 3 Aug 2020 10:58:47 -0700 Subject: [PATCH 5/8] Fixed typo in bullets --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 4c85fa6..677606d 100644 --- a/README.md +++ b/README.md @@ -55,7 +55,7 @@ If you copy these in your bash profile you wont have to look for them again. We This step reserves the DOI for the paper, allowing you to update metadata before final publication. -4.\ 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: @@ -67,7 +67,7 @@ Article DOI: 10.xxxx/zenodo.xxxxx Article URL: https://sandbox.zenodo.org/record/xxxxxx/file/article.pdf ``` -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. +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 From a4e7a09eee2634f7b0d486f7ff9e734ba96481cc Mon Sep 17 00:00:00 2001 From: Karthik Ram Date: Mon, 3 Aug 2020 13:33:13 -0700 Subject: [PATCH 6/8] more cleanup --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 677606d..247de88 100644 --- a/README.md +++ b/README.md @@ -12,17 +12,17 @@ Have these two files ready before cloning this repository. There are 5 parts to publishing the article. -| Step | What it does | +| 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) | Reserves the DOI | +| [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 publish a ReScience article +### 14 steps to publishing a ReScience article 1\. Clone this repository locally. 2\. Copy the authors `metadata.yaml` and `article.pdf` into this folder From 8567d8b565409d32ac1d32326ba813d0f6776e52 Mon Sep 17 00:00:00 2001 From: Karthik Ram Date: Tue, 4 Aug 2020 10:56:23 -0700 Subject: [PATCH 7/8] Added couple more instructions --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 247de88..278991d 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ This document is intended for ReScience editors. Congrats on accepting a ReScien - The article metadata file (`metadata.yaml`) from the author's repository. At this time the metadata file should **will be missing** the article DOI, number and URL. This is expected and something you will fix over the coming steps. - The final article itself (`article.pdf`) -Have these two files ready before cloning this repository. +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 @@ -92,7 +92,7 @@ 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 is: +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 From b850118d34903c5f8befe99141a0cde895b00ef4 Mon Sep 17 00:00:00 2001 From: Karthik Ram Date: Thu, 6 Aug 2020 11:41:00 -0700 Subject: [PATCH 8/8] Fixed khinsen's edits --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 278991d..1f2e1e7 100644 --- a/README.md +++ b/README.md @@ -3,8 +3,8 @@ 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 should **will be missing** the article DOI, number and URL. This is expected and something you will fix over the coming steps. -- The final article itself (`article.pdf`) +- 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. @@ -48,7 +48,7 @@ And to check it was set correctly: echo $ZENODO_SANDBOX_TOKEN echo $ZENODO_TOKEN ``` -If you copy these in your bash profile you wont 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. +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 @@ -99,7 +99,7 @@ You should complete the missing information and verify the whole file before mov - acceptance and publication date - issue, volume, and article numbers. -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, have them `Make` a new `article.pdf`. The PDF will now contain the volume, article number and DOI. +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. 10\. Copy the newly updated `article.pdf` and `metadata.yaml` back to this repo.