The readthedocs rendering of the spec should advertise the version

[sappelhoff]

https://bids-specification.readthedocs.io/en/stable/ does not advertise its version on the main landing page, we should probably change this.

Perhaps display it somewhere in this corner?

[franklin-feingold]

It could go in the top corner, I am not sure if there are readthedoc limitations (looking into it). Perhaps it could go into the text as a third paragraph indicating the latest stable release? (under the get started paragraph)

[sappelhoff]

Perhaps it could go into the text as a third paragraph indicating the latest stable release? (under the get started paragraph)

yes, that would be an easy to do alternative. But in the corner would be preferable I think, because it can be seen regardless of the sub-page a reader might currently be on.

[franklin-feingold]

We are able to edit the corner header by changing the site_name in the mkdoc.yml. However, it is not immediately clear how this permeates across stable and latest releases (I think to both, but further simulations are needed to confirm my suspicion). Regardless though I think latest and stable will be part of the same version because stable takes the latest release and latest is current to master. Master should not be version(s) ahead (i.e. stable at v1.1.2 and master at v1.1.3 without a release).

If we do find there are different versions across necessitating more dynamic version control site_name, It appears this has been discussed over at mkdocs since 2014. There appears to be a solution called mike that could handle this exact versioning issue.

[sappelhoff]

Regardless though I think latest and stable will be part of the same version because stable takes the latest release and latest is current to master. Master should not be version(s) ahead (i.e. stable at v1.1.2 and master at v1.1.3 without a release).

yes, master should never be a version ahead of the latest release in my opinion. I think of it as:

• stable 1.1.2
• master 1.1.2-dev

i.e., only adding -dev to the stable version to indicate that this is the latest version.

would be cool if we could add the -dev suffix to the version for the "latest" rendering of readthedocs.

[franklin-feingold]

That sounds good to me. I think this all can be integrated and be a part of the Release Protocol. I will start putting together how that would look and submit a PR.

[sappelhoff]

@franklin-feingold since #137 has been merged, this issue can be closed - correct? If I understand it correctly, we will have the version advertised when making a new release?

[franklin-feingold]

yup! this issue can be closed and yes as we go through the Release Protocol this should have the version at the top for the stable and latest versions of the specification

[sappelhoff]

great, thanks again!

[sappelhoff]

it's working as expected and looking good :-)