search

samtools / hts-specs

Specifications of SAM/BAM and related high-throughput sequencing file formats
http://samtools.github.io/hts-specs/
655 stars 173 forks source link

Accessing older versions of refget and htsget #629

Open andrewyatz opened 2 years ago

andrewyatz commented 2 years ago

The refget call on 2022-02-01 raised an issue about an impending version bump to refget and providing access to previous versions of the specification for future access e.g. another specification has made reference to them. We discussed two models

  1. Providing hash commit links to a point in the hts-spec repo where the spec was at a given version. These links would be added to the spec as a list of permalinks
  2. Create tags in hts-spec with specific names to indicate what is being tagged
  3. Making a copy of the specification much as VCF has done

We took a straw-poll with our preferences being 1, 3, 2. Is there value in aligning refget and htsget in how they approach this issue.

jmarshall commented 2 years ago

Htsget now has a version history appendix. As discussed on #585, we plan to turn the subheadings in that appendix into links to https://github.com/samtools/hts-specs/blob/COMMITHASH/htsget.md; i.e. the current version would be formatted with Jekyll at https://samtools.github.io/hts-specs/htsget.html (as at present) while older versions will be available linked from that, in the slightly inferiorly rendered repository view. See PR #644.

TL;DR htsget concurs with (1).

andrewyatz commented 2 years ago

Excellent news. This would mean we should follow option 1 to remain in-line with what htsget is doing and extend the history appendix already available. Thank you @jmarshall. The lack of links in the current spec made me think this hadn't been discussed but this is perfect

jmarshall commented 2 years ago

The htsget version of this has now been merged. See the links in the htsget version history.

See also the little bit of liquid templating at the top that adds “This printing is version [d97f9e] from the [hts-specs] repository” akin to the PDF specs. IIRC it was @tcezard who suggested trying to figure out how to do this in GitHub Pages / markdown.

andrewyatz commented 2 years ago

That Github Metadata plugin is an absolute goldmine. Well done @jmarshall for finding it