Skip to content

Clean up README and clarify instructions #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Aug 10, 2020
Merged

Clean up README and clarify instructions #13

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
a5ad591
Updated readme based on discussion at #11
karthik Aug 3, 2020
5f14389
Clarified audience and added links in toc
karthik Aug 3, 2020
977098b
More clarification
karthik Aug 3, 2020
67297bf
Added missing bullets
karthik Aug 3, 2020
5f37e53
Fixed typo in bullets
karthik Aug 3, 2020
a4e7a09
more cleanup
karthik Aug 3, 2020
8567d8b
Added couple more instructions
karthik Aug 4, 2020
b850118
Fixed khinsen's edits
karthik Aug 6, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
143 changes: 84 additions & 59 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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:
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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 <DOI>
```


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! 🎉 🚀