Skip to content

Commit

Permalink
Updated readme based on discussion at #11
Browse files Browse the repository at this point in the history
  • Loading branch information
@karthik
karthik committed Aug 3, 2020
1 parent e180a68 commit a5ad591
Showing 1 changed file with 83 additions and 58 deletions.
141 changes: 83 additions & 58 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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/).
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.
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 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
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! 🎉 🚀

0 comments on commit a5ad591

Please sign in to comment.