How to handle releases of markdown document on github

Question

We have a group-developed metadata conventions document for a particular group of ocean models stored as github-flavored markdown at https://github.com/ugrid-conventions/ugrid-conventions and now we would like to "release" the current version of this markdown document at version 1.0 (and continue the development of the conventions for future releases).

I understand that github has releases, but we don't want a zip file containing the markdown document, we just want a "version 1.0" markdown document. We could also like to preserve the changes so that people can see what changed relative to previous versions as we go forward.

Should we just copy the existing document ugrid-conventions.md to ugrid-conventions_v1.0.0.md, or is there a better way?

Answer 1

I'd suggest creating a tag for each release. Tags automatically get listed on GitHub's Releases page (in fact, every Release is associated with a tag), and you can also link directly to files within a tagged commit. For example, if you created a tag named v1.0, you could send folks to https://github.com/ugrid-conventions/ugrid-conventions/blob/v1.0/ugrid-conventions.md to see the 1.0 version of that file.