Links to previous BIDS versions

[nicholst]

While the focus is moving the BIDS standard ahead, it's important to realise that many users depend on targeting a fixed standard. For example, when we work with industry we need to be able to say we create data compliant with a given version of BIDS. But as the standard is advanced, it can then be a problem if that version is no longer available/findable.

So! I started on the website with no luck and then in the Changelog, and only just now remembered that some previous versions are available in the floating read-the-docs menu in the lower right.

Do people agree that the logical place is both the website and the ChangeLog (or somewhere else in the doc?) (Or maybe just add text in the ChangeLog to reference the floating menu?)

[franklin-feingold]

We preserve all previous version of the specification on our website github

Perhaps a new tab on the website with links to the previous versions of the specification? The floating menu only gives versions since we merged over to github so the new tab can be to encompass all previous versions and ease locating them. My concern with the changelog is how it is generated will require some development to achieve this and how beneficial it would be to place it there (these previous should be placed somewhere thinking the website may be more beneficial)

[nicholst]

Sounds like adding a “Version History” tab (or something) on the website, with links to each version, would be most practical and useful. --

---

Thomas Nichols, PhD Professor of Neuroimaging Statistics Nuffield Department of Population Health | University of Oxford Big Data Institute | Li Ka Shing Centre for Health Information and Discovery Old Road Campus | Headington | Oxford | OX3 7LF | United Kingdom T: +44 1865 743590 | E: thomas.nichols@bdi.ox.ac.uk W: http://nisox.org | http://www.bdi.ox.ac.uk

[sappelhoff]

Thanks for raising the point, I agree that this is important.

All versions 1.1.2 and higher can be easily displayed by readthedocs, using the small panel from the spec website to navigate:

I guess the issue revolves more around the "old" versions of BIDS prior to the move to GitHub.

As far as I see, these would be (excluding release candidates):

• 0.4 (perhaps also exclude?)
• 1.0.0
• 1.0.1
• 1.0.2
• 1.1.0
• 1.1.1

It would be ideal to somehow also include them in the navigation panel of readthedocs and then simply link to the pdfs ... which we could then store as fixed, historical pdfs on our bids-specification repo (i.e., migrate them from their current storage on the bids-website)

I am against storing the old specs on the website, because of the several work streams trying to narrow down the spec as ONLY the spec, and the website as a hub for links and other important information (see e.g., https://github.com/bids-standard/bids-specification/pull/389)

That said, if we cannot achieve an ideal situation ... I favor the practical solution over none (i.e., using the website)

[nicholst]

I'm not too fussed about where the old versions are but they must be easily findable, which is not presently the case.  The floating menu is handy, but it's not an intuitive place and doesn't have all the previous versions. 

@sappelhoff - Did you mean to make a distinction between the website hosting vs. just linking the previous versions? To me, website is the obvious place to look if looking for old versions. However, if it is cleaner, links to old versions could be within in the spec itself only, and then the website could direct people to look in that section of the spec for the old versions.

[sappelhoff]

I think that the specification including its changelog and all prior versions should be hosted and stored on the bids-specification repository.

The floating menu is handy, but it's not an intuitive place and doesn't have all the previous versions.

I have to agree with the floating menu not being very intuitive / visible to newcomers

re: previous versions --> we'd have to check whether one can manually add links there for the old BIDS pdf version

However, if it is cleaner, links to old versions could be within in the spec itself only, and then the website could direct people to look in that section of the spec for the old versions.

Yes, I think this would be cleaner. Let's see what other people think!

[robertoostenveld]

good point, I also think that previous versions MUST remain accessible. Just some thoughts:

1. I would prefer the technical details and provenance of the specification(including the small issues, typo corrections etc) to be all hosted on the bids-specification repository on github. That facilitates maintenance and increases the chance of future "porting" the content of the specifications to whatever system is going to replace RTD in X years from now.
2. I would prefer all specifications to be viewable on a single place (not a PDF here and a HTML there). That facilitates side-by-side comparisons by end-users.
3. I think it would be good if https://bids.neuroimaging.io/specification would provide links to the current and previous specifications, and include a short piece of text that explains how various stakeholders should deal with different versions.

I would be willing to invest some time in porting the older specifications from PDF to markdown in a format that would work for the git repository and RTD. However, it is not clear to me how the RTD versions relate to github tags or releases and how a previous version could be added to the current documentation system.

[sappelhoff]

However, it is not clear to me how the RTD versions relate to github tags or releases and how a previous version could be added to the current documentation system.

The readthedocs versions that are built can be activated from the readthedocs admin website that some maintainers (e.g. @effigies @franklin-feingold and I among others) have access to.

Active versions are built whenever new code is pushed to that branch or tag.

So you can add a branch or a new git tag and then activate a build for it.

For the old BIDS versions, we could:

1. make an individual branch for each old version and activate the build of each of those branches
2. somehow set the bids-specification repo state to an old BIDS version (manually), ... then tag it ... then reset

I am not at all sure how option 2. would work and it seems like a bad idea.

I would be willing to invest some time in porting the older specifications from PDF to markdown in a format that would work for the git repository and RTD.

I think such a port might be very error prone and labour intensive, wouldn't it?

Perhaps having an additional "page" (within the BIDS specification) where we talk about versions, and provenance, and then link to the old PDFs (to be hosted in our spec repo) might be better.

We could also use this page to write a small sentence about the hovering RTD panel that many users don't seem to find intuitive for switching around versions.

[sappelhoff]

closed in https://github.com/bids-standard/bids-specification/pull/452 and https://github.com/bids-standard/bids-website/pull/119

remaining PDFs are soon to be uploaded, as tracked in https://github.com/bids-standard/bids-specification/pull/407