[DO NOT MERGE] Track adding of old PDF versions to Zenodo

[sappelhoff]

In this PR I am adding the bids specification PDF files for the versions that were released prior to our move to GitHub as a platform.

See #392 for context.

I am adding the following versions:

1.0.0
1.0.1
1.0.2
1.1.0
1.1.1

I took the pdfs from the old bids website, where they were originally hosted and where they are still archived: https://github.com/bids-standard/bids-website/tree/gh-pages/old_website

I propose to not include the release candidate versions (rc), because they shouldn't be treated equal to a release. Side note: I cannot find 1.0.0-rc3 anywhere.

Note that the pdf for version 1.1.0 was 6MB of size, so I removed the embedded fonts to shrink it. Furthermore, I ran all of the files through some online shrinking service, further reducing the size. To my inspection, the quality has not suffered from this treatment.

To discuss:

• where exactly to store the PDFs --> I am currently proposing a separate directory from the root ./historical_pdfs

  • -> the PDFs will NOT be added to the repo, and instead stored on Zenodo
  • -> a "dev" PDF is available on each build from this link: https://circleci.com/api/v1.1/project/github/bids-standard/bids-specification/latest/artifacts/0/bids-spec.pdf?branch=master
  • -> upon the each release starting from v1.3.0, a new versioned PDF will be built and added to the Zenodo collection

• how to link to the historical PDFs. This could be done in a separate PR. One place could be the changelog file, where each version heading is a link to that version. See also: REL: v1.2.2 #405 (comment)

  • -> in addition to linking in the changelog file, we'll add a paragraph to the SPEC (to be discussed where exactly) mentioning where on Zenodo to find old PDFs

[yarikoptic]

Please no rendered PDFs as is in this repo. It will be of no benefit to any contributor - it will make repo grow, clone and fetch slow down, etc

Use git lfs, annex, or just place into a separate git repo, which you can include as optimal submodule here.

[sappelhoff]

Please no rendered PDFs as is in this repo

Usually I would agree, but these PDFs are arguably a special case.

• They will not change, so they won't blow up the history beyond their initial file size
• They will remain the only PDFs added to the repo, because the "new" pdf (see pdf version of spec #135 and connected issues/prs) will be generated on each build (and "stamped" according to its version), but stored either on ReadTheDocs or CircleCI (we have to check)
• Conceptually it makes sense to have all specifications in one place
• The drop in speed for cloning etc. will not be very noticable

But let's hear what other contributors have to say.

[robertoostenveld]

I consider this a valuable addition to the specification repository. It is good to have the old versions here, rather than scattered over the intertubes.

[yarikoptic]

Conceptually it makes sense to have all specifications in one place
...
It is good to have the old versions here, rather than scattered over the intertubes.

... and the counter argument to those is in the aforementioned item:

the "new" pdf (see #135 and connected issues/prs) will be generated on each build (and "stamped" according to its version), but stored either on ReadTheDocs or CircleCI (we have to check)

So -- they will be spread around, unless we centralize explicitly. E.g. this repository could reference (urls) them from the corresponding locations (a dedicated repo with historical PDFs and RTD for new ones). Or we could even setup automated population of that dedicated repo with newer versions as well.

I really do not see sticking historical PDFs (only) into this repository (of sources) solving a problem of scattering PDFs around.

[robertoostenveld]

What about having the PDFs at a place where they will remain persistent and each get their own DOI? E.g. Zenodo? This could be done for past PDF versions, but in principle also for current and future versions (when rendered as PDF).

[KirstieJane]

Heya! I like the idea of putting the PDFs in a zenodo archive.

We could make one repository, and then upload the PDF files in the order of oldest to newest, doing a new release (giving a new doi) for each. That means we can have one DOI for each version, and one link that will go to the latest version of the DOI (https://help.zenodo.org/#versioning).

That way we can keep the persistant archive of all the PDFs in one place.

We could maybe add a section to the specification on "how to find previous versions" and include those dois?

[effigies]

I'm 👍 for Zenodo archiving the old version. One concern I'd have is to ensure that the PDF can be directly accessed by URL, and not just the landing page.

When a GitHub release is archived to Zenodo, it's zipped, rather than making all of the individual files directly available. So I'd just want to check that not everything gets hidden in a zip and turned into a multi-click exercise.

[effigies]

Has somebody already started posting these to Zenodo? Should I do that? Do we need to finally set up the bids-maintenance user (#332) so that no one person becomes a bottleneck for working on Zenodo?

[sappelhoff]

Has somebody already started posting these to Zenodo?

no, not yet

Should I do that?

I think we should first address your own concern: "ensure that the PDF can be directly accessed by URL, and not just the landing page"

If Zenodo does not work for this, we could think about alternatives:

• figshare? (I would prefer not to use it)
• An OSF page for each spec? ... owned by a BIDS OSF user? (similar to the bids-maintenance user)

Do we need to finally set up the bids-maintenance user (#332) so that no one person becomes a bottleneck for working on Zenodo?

yes! And share the password for that user among the maintainers.

[effigies]

Zenodo entry: https://zenodo.org/record/3686062
Direct download link: https://zenodo.org/record/3686062/files/bids_spec1.0.0.pdf

I used the date of bids-standard/bids-website@7430397 as the publication date, and retrieved the author list from https://www.frontiersin.org/10.3389/conf.fnins.2015.91.00056/event_abstract as a first approximation. Metadata can still be edited, but the data archive itself is no longer editable.

We should be able to add new versions straightforwardly. The contributors list shows up in 1.1.0, so we can be a little more definite at that point.

The @bids-maintenance user created the entry, so anybody with access to that (I can share the password over a secure channel) can update metadata and add new versions.

[sappelhoff]

great, thanks a lot @effigies.

If I understand correctly, we'll have a single DOI for the PDFs ... but different download links? See this screenshot from the zenodo page:

---

Remaining TO DOs:

• edit the original post of this PR to better reflect the results of the discussion
• upload the remaining "old" BIDS versions one by one, getting a new download link for each, and making sure to adjust the contributors starting with version 1.1.0
• add a section to the BIDS specification about where to find the PDFs of the specification ... and determine where that section should be in the spec

[effigies]

There will be a common DOI and a specific DOI per version.

[sappelhoff]

actually, looking at my To Do list in #407 (comment)

I realized that if we are to get DOIs for each spec, we have to get back to #66

and discussing the authorship order for each spec. That was easy for the version that @effigies uploaded (because it already existed). For the other specs, we'll have to first find a consensus.

[bids-maintenance]

I am adding the remaining PDFs one by one to zenodo now. Just for documentation purposes, I get the publication dates from these commits:

• 1.0.1 bids-standard/bids-website@ff9ccf4
• 1.0.2 bids-standard/bids-website@ddd73c3
• 1.1.0 bids-standard/bids-website@d0a0570
• 1.1.1 bids-standard/bids-website@6ea0e1a

Remaining To Dos (copied over from #407 (comment) )

• editing the Release Protocol to include a short section on how to generate PDF for a version of the spec, and then how to upload it to Zenodo
• improve attribution of contributors ( [DISCUSSION] acknowledge contributors in DOIed specs on Zenodo #66 ) and metadata of zenodo entries

not relevant anymore

[sappelhoff]

I renamed #66 and edited the OP to reflect that we need to finish discussing author order.

Discussion can continue there, I am closing this PR, because it's original goal has been achieved in other ways.