aboutsummaryrefslogtreecommitdiffstats
path: root/guide/src/editing_quickstart.md
blob: df413fcc0e0a0c6b8d0b459e788a08ec169094f5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

# Editing Quickstart

This tutorial describes how to make edits to the Fatcat catalog using the web
interface. We will add a new `file` to an existing `release`, then update the
release to point at a different `container`. You can follow these directions on
either the [QA](https://qa.fatcat.wiki) (NOTE: QA not available as of Spring
2021) or [production](https://fatcat.wiki) public catalogs. You will:

- create an editor account and log-in
- create a new `file` entity
- update an existing `release` entity
- submit editgroup for review

First [create an editor account](https://fatcat.wiki/auth/login) and log-in. If
you don't have an account with any of the existing federated log-in services
(eg, Wikipedia, ORCID, Github), you can
[create a few Internet Archive account](https://archive.org/account/signup),
confirm your email, and then log-in to Fatcat using that. You should see your
username in the upper right-hand corner of every page when you are successfully
logged in.

Next find the release's fatcat identifier for the paper we want to add a file
to. You can [search](https://fatcat.wiki/release/search) by title, or
[lookup](https://fatcat.wiki/release/lookup) a paper by an identifier (such
as a DOI or arXiv ID). If the release you are looking for doesn't exist yet,
you'll need to [create](https://fatcat.wiki/release/create) a new one. All of
these actions are linked from the Fatcat front page for each entity type.

The release fatcat identifier is the garbled looking string like
`hsmo6p4smrganpb3fndaj2lon4` which you can find under the title of the paper's
[entity page](https://fatcat.wiki/release/hsmo6p4smrganpb3fndaj2lon4), and also
in the URL. You'll need this identifier to link the file to the release.

Before creating a new file entity (or any entity for that matter), check that
there isn't already an entity referencing the exact same file. Download the
file (eg, PDF) that you want to add to your local computer, and calculate the
SHA-1 hash of the file using a tool like `sha1sum` on the command line. If you
aren't familiar with command line tools, you can upload to a [free online
service](http://onlinemd5.com/). The SHA-1 hash will look like
`de9aefc4522b385121e72faaee75bda9fbb8bf6e`, and you can do a [file
lookup](https://fatcat.wiki/file/lookup). If a file already exists, you could
edit it to add new URLs (locations), or add/update any release links.

Assuming a file entity doesn't already exist, go to [create
file](https://fatcat.wiki/file/create). We will want to start a new "editgroup"
for these changes. If you don't have any editgroups in progress, you can just
enter a description sentence and a new one will be created; if you did have
edits in progress, you'll need to select the "create new editgroup" option from
the drop-down of your existing editgroups.

Enter the basic file metadata in the fields provided. The red stared fields are
required (size in bytes and SHA-1). Add a URL on the public web where the file
can be found. It's best if PDFs are uploaded to repositories (eg,
[Zenodo](https://zenodo.org)) or hosted on the publisher's website. A second
archival location can be added (eg, using the Wayback Machine's ["save page
now"](http://web.archive.org/save) feature), or you could skip this and wait
for a bot to verify and archive the URL later. The left drop-down menu lets you
set the "type" of each URL. Add the release identifier you found earlier to the
"Releases" list.

Add a one-sentence description of your change, and submit the form. You will be
redirected to a provisional ("work in progress") view of the new entity. Edits
are not immediately merged into the catalog proper; the first need to be
"submitted" and then accepted (eg, by a human moderator or robot).

Let's add a second edit to the same editgroup before continuing. The new file
view should have a link to the release entity; follow that link, then click the
"edit" button (either the tab or the blue link at the bottom of the infobox).
This time, the most recent editgroup should already be selected, so you don't
need to enter a description at the top. If there are any problems with basic
metadata, go ahead and fix them, but otherwise skip down to the "Container"
section and update the fatcat identifier ("FCID") to point to the correct
journal. You can [lookup journals](https://fatcat.wiki/container/lookup) by
ISSN-L, or [search](https://fatcat.wiki/container/search) by title. Add a short
description of your change ("Updated journal to XYZ") and then submit.

You now have two edits in your editgroup. There should be links to the
editgroup itself from the "work-in-progress" pages, or you can find all your
editgroups from the drop-down link in the upper right-hand corner of every
page (your username, then "Edit History"). The editgroup page shows all the
entities created, updated, or deleted, and allows you to make tweaks (re-edit)
or remove changes. If the release/container update you made was bogus (just as
a learning exercize), you could remove it here. It's a good practice to group
related edits into the same editgroup, but only up to 50 or so edits at a time
(more than that becomes difficult hard to review).

If things look good, click the "submit" button on the editgroup page. This will
mark your changes as "ready for review", and they will show up on the [global
reviewable editgroups](https://fatcat.wiki/reviewable) list. If you change your
mind, you can "unsubmit" the editgroup and make more changes. Humans and bots
can make annotations to editgroups, recommending changes. At the current time
there are no email or other update notifications, so you need to check in on
annotations and other status manually.

When your changes have been reviewed, a moderator will "accept" them, and the
entities will be updated in the catalog. Every accepted editgroup ends up in
[the changelog](https://fatcat.wiki/changelog).

And then you're done, thanks for your contribution!