[INFRA] link to changelog of specific BIDS version seems broken in docs

[sappelhoff]

This link shows our changelog: https://bids-specification.readthedocs.io/en/stable/CHANGES.html

clicking on the "v1.2.0" label, I get a 404 Error. Anyone else with these problems?

quicklink: https://bids-specification.readthedocs.io/en/v1.2.0/

clicking on the other labels actually leads to our Github page.

Can anyone replicate this? What's the issue here?

[PeerHerholz]

Same here.
As you already mentioned, the "v1.2.0" link points to https://bids-specification.readthedocs.io/en/v1.2.0/ instead of https://github.com/bids-standard/bids-specification/tree/v1.2.0.

Checking the *.md files in src and the website, it appears that all most recent changes are not reflected. This includes for example #155, #156, #157, #161, #162, #166, #167 and #176 wrt Changes.md; #178 wrt 02-common-principles.md and #179 wrt 01-introduction.md.

Maybe the result of some problems related to builds/tests?

[franklin-feingold]

Thank you @sappelhoff and @PeerHerholz for raising this. On our stable builds, the stable tag is set upon a release (github release). This is why you may see that recent changes are not reflected in the changelog on stable, but if you look at our latest build those changes are present. If they are not there, the CHANGES.md is generated on each merged PR into the master repo.

It appears the previous stable release (https://bids-specification.readthedocs.io/en/v.1.1.2/) renders okay. I am curious if this has to do with conflicting stable and versioned build (they are currently the same right now). IMO it is probably more helpful to link out to that versioned stable build (i.e. v.1.1.2 to the rendered readthedocs vs github).

Another part to note is that upon each generation the links are regenerated as well, so on our latest build all of them are linking out to the github page. One way this can be stopped would be to tinker with the changelog generator and put the most recent releases into the pregh-changes.md (and likely change the name of the file because it would contain more than just the pregh changes) and add an additional option to the generator to only generate from the most recent release. So the links that are changed are cemented and not needed to be changed anymore. The changelog generation is being done automatically by circleCI.

[sappelhoff]

There is furthermore an issue with the names of the release 1.1.2: See the image

It lists an additional v.1.1.2 on top of the correct v1.1.2 (see also our tags)

This is also a bit mixed on our releases page: https://github.com/bids-standard/bids-specification/releases

[franklin-feingold]

This is due to the first release on github there was an issue regarding how to name the versioning (the versioning should follow the github standard) That was not the case in the initial release which is why you see two versions of the same release.

[sappelhoff]

This is due to the first release on github there was an issue regarding how to name the versioning (the versioning should follow the github standard) That was not the case in the initial release which is why you see two versions of the same release.

Would it be smart to delete the erroneous release?

[franklin-feingold]

It would be good. It would be changing the current way the changelog is generated. Upon each regeneration (a merged PR) it will come back because the full log (since the github merge) is generated each time. One potential way would be to have the generator only go from the latest tag to recent. This is connected with the other conversations regarding the changelog like how we want the changelog to look with the labels to make it more human readable. Luckily the tools are there to accomplish this

[effigies]

Fixed with a rebuild of v1.2.0 on ReadTheDocs. I also removed the old tag. There's no changing the changelog in old versions, but it should be fixed for the next one one.