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?
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.
Related
I have quite a lot of 'hardcoded' pieces of information in the README of my Github repo.
The user name : instead of my username, can I put something like $USER (whatever the syntax is) ? I have some links, badges, that contain the user name. That causes issues when doing forks and then the same issue the other way around when doing pull requests.
The latest release : instead of hardcoding the latest release number in the readme, is it possible to use an existing variable ? In my particular case, I want to put a link to the latest release available on jitpack.io. It looks like https://jitpack.io/com/github/somebody/somerepo/something/2.0/something-2.0.zip
There are no variables in a README. A README is just a normal Markdown (or AsciiDoc, etc.) document that happens to be rendered on the main page of the repository instead of requiring that the user browse to it directly.
It may be that for the jitpack.io URL, there's a special latest version URL that you can use, but you'd have to check their documentation. I'm not personally aware of one. You could of course host a server that performs the correct redirects to your badges and release assets automatically (or proxies them), but there's no way to modify the README to make it anything other than a static document.
I've joined a project which uses Github actions & releases. Unfortunately, naming convention of release tags changed in the past (probably due to migration from Travis CI).
Until a certain point of time, the tags were like this (not sure why the numbers were so high):
v1018.0.0
v1018.1.0
v1020.0.0
v1024.0.0
Then someone switched to semantic versioning (which is great btw):
v2.5.1
v3.0.0
v3.1.0
v3.1.1
Our CI/CD works just fine, but we have some issues:
We use Release Drafter. It creates a description for a new release which should consist of all PRs since the previous release. But now it compares current state of our master branch not with the latest tag (v3.1.1), but with a tag with the highest major number (v1024.0.0). Which means the draft always consists of 100+ PRs merged since one year ago. So we end up deleting the whole release description, because noone has time to analyse that.
It's messy. Github always suggests v1024 as the newest version: when creating new releases, when switching between tags and so on.
My two questions are:
Is there any safe way to update names of all old tags? F.e. change v1024.0.0 into v0.1024.0. Doesn't have to be automatic. Keep in mind it should update the tagnames only, I don't want to change release date, assets etc. I think that editing a release using Github UI would in fact create a new tag based on master (and maybe even release it to live server?)
If not, is there any way to tell Release Drafter that it should use the latest tag instead of the highest one?
Well a little googling would tell you many things :)
How do you rename a Git tag?
https://gist.github.com/rponte/fdc0724dd984088606b0
Yes you can update tags (see first link)
Yes you can get the latest tag - see second link.
I document my software using the README.org file, which is rendered nicely in the master branch in GitHub. Now, suppose I create a tag v1.0 and want to share a link to that tagged version with others. Unfortunately, when one follows that link, he does not find my README.org nicely rendered, but only the archived code. So, what is the correct way of documenting a tagged version at GitHub? (of course, I am looking to re-use my README.org).
Right now to find out the current tag of a repo I have to clone the repo and run git tag.
Is the tag published somewhere on github?
Just want to make sure I'm not overlooking it somewhere.
The following formatted url will display the list of tags of the repository, with the most recent at the top
https://github.com/{:owner}/{:repository}/tags
You also can access this list by clicking on the Releases link on the main page of the repository, then on the Tags link.
Note: FWIW, in git parlance, there's no such thing as a current tag.
Tags are basically labels, names. They can exist in two flavors:
lightweight pointers to some commits (or trees (think directories) or even blobs (think files))
annotated pointers to the same kind of git objects as above. The annotation adds some additional information as the identity of the person who created the tag, the date of the tagging and optionally a cryptographic signature.
Tags are most of the time used to stamp a version. They can also be used to "bookmark" a specific object (while doing a code review, for instance).
So depending of what one use tags for, the current tags may be:
The tag pointing to the most recent commit
The latest created tag (if annotated)
The last one when their names are alpha sorted (or whatever sort mechanism matching the tag naming convention for this specific repository)
Does Github offer the option to create release-page for a project? I've noticed it let you create different tag for the source, but couldn't find the UI/web where I can add release notes, built package(s) and all that.
Update 2d July 2013, you now can define a release.
Releases, a workflow for shipping software to end users.
Releases are first-class objects with changelogs and binary assets that present a full project history beyond Git artifacts. They're accessible from a repository's homepage:
Releases are accompanied by release notes and links to download the software or source code.
Following the conventions of many Git projects, releases are tied to Git tags. You can use an existing tag, or let releases create the tag when it's published.
You can also attach binary assets (such as compiled executables, minified scripts, documentation) to a release. Once published, the release details and assets are available to anyone that can view the repository.
That is what replaces the old binary upload service, which was removed in December 2012!
Initial answer (February 2012)
Not that I know of: this is very dependent of each project language and release management process.
One way would be to use the README.md to publish those information, or to link to the release notes as a separate document.
The nice detail about a link is that it can, since a few weeks, be a relative one (see blog post "Relative links in markup files").