17

What is the reason to use release version as a release title on GitHub?

It looks like this enter image description here And it looks like a common practise. Almost all popular repositories use it.

What is the use case to duplicate release tag to the release title?

UPDATE:

Examples: Facebook React, Atom, Kubernetes, CryEngine

8
  • Show us the actual posting where you saw this. This little screenshot doesn't tell us anything; we don't even know what the repository is. Mar 27, 2017 at 15:12
  • @RobertHarvey added 5 examples. But the question is not about some repositories. It's about usage of "release titile" on GitHub in general.
    – user980828
    Mar 27, 2017 at 15:21
  • 6
    What else would you use? Random dictionary words? Emoticons? Or are you complaining that they don't add the project name as a prefix? Mar 27, 2017 at 15:21
  • 1
    Are you expecting projects to give unique names to releases? That seems...unnecessary.
    – Thomas Owens
    Mar 27, 2017 at 15:23
  • 2
    The "main functionality" will be in the description below, where it belongs, because often there is way more functionality in a release than can be included in a title. It makes perfect sense to me that that title of the release will be the specific version number. It might help to turn your question around and ask why there's a git tag that duplicates the release title. The answer to that is that git tags are useful, but in a different way than a release title.
    – Eric King
    Mar 27, 2017 at 15:31

4 Answers 4

24

How to manage release with Git and GitHub ?

The Git standard way of identifying a release is to create a version tag. This tag marks a specific version of your software in the change history of your repository. Most teams work with tags, because these are directly available in the repository and can be used in git commands.

The releases are a GitHub feature for packaging software for delivery. This allows to add some downloadable binaries associated to the release. So, in practical terms, the release is some added web content related to a tagged version; it's not something known in you local repository.

To create a release on GitHub, you have to enter a mandatory new tag identifier (that will be created to identify the release) and an optional release name.

Naming conventions

As the tags are the primary identification of a release, it's managed with care. Usually it follows the semantic versioning convention (or some variant).

For the name, there is no universal convention. But if it is left empty, GitHub will simply take over the version tag that you've just created. This is why so many projects reuse the tag id for the release name: it's not a deliberate choice; they don't even have to do a copy-paste; it's just that they had no desire/time/interest in using a more creative description, and let GitHub define it by default !

You can of course use a different convention. You could perfectly use a code name (e.g. "Longhorn SP2" instead of "v6.0.6002" like Microsoft is doing for Windows, or "Ice cream sandwich" instead of "v4.0.4" like Google is doing for Android). But maintaining such a naming standard in the long run requires a lot of creative people if you want to keep the names unique. More realistic is a mixed approach: use the default version tag for minor releases, but identify a codename for important releases (especially if these are significant for marketing)

You could also think of identifying main new features. However this is of very limited use. First, if you're adept of separating corrective releases and functional releases (as proposed by ITSM version release management guidelines), you would have some troubles finding a meaningful name for half of your releases. Then, this scheme works only with small software: if you have an enterprise grade software, the main functions would be far too difficult to summarize in the couple of words that remain visible on the GitHub release page. This kind of information is best put in a release note.

6

This is a larger screenshot of the actual page you found.

enter image description here

Notice that it says Docker/Toolbox in the upper left hand corner of the page, so you already know what this page is about.

The title of the page is v17.04.0.ce-rc1, because that's the version of Docker/Toolbox that is being released. Savvy readers will recognize that this is a Release Candidate, as evidenced by the "Pre-release" indicator and the rc1 as part of the version number.

In short, if you look at the whole page (instead of just the obtuse title), it does make sense.

I would also note that it was quite easy to find this in Google, just by searching on the release number you gave me.

17
  • 4
    The question is not about version naming. It's about usage of GitHub functionality. Why do we need release title if it's always equals to release tag?
    – user980828
    Mar 27, 2017 at 15:28
  • 3
    No, the answer is "because v17.04.0.ce-rc1 is a more specific and descriptive title." That it also happens to be the same as the version number on the release tag is just a coincidence. Mar 27, 2017 at 15:40
  • 4
    Coincidence doesn't necessarily mean raw chance, it means two independent things that happen at the same time. There's a good reason to have the release title be the version number, as explained above. There is also a good, separate reason to have a git tag with the version number for each release. The fact that they both appear on the same page in close enough proximity to give you confusion is coincidence.
    – Eric King
    Mar 27, 2017 at 16:33
  • 1
    @EricKing Release title is not used because everyone just copy-pastes release tag to the title. I mean it just looks redundant.
    – user980828
    Mar 27, 2017 at 16:48
  • 3
    I would be fairly irritated if I didn't have the choice. Maybe I want to put "Release Candidate Bluecreek, Version 17.04.0.ce-rc1" as the page title instead. That most people just paste the version number into the title creates a reasonably good informal convention. But it's not a rule or law, or even a guideline. It's simply that Github was polite enough to give us the choice to put something else in the title. Mar 27, 2017 at 16:56
1

Why even have a release title at all?

You can push just a version as a tag, but Github will not show it as the 'latest' release on the github page unless you give it a release title. Many projects suffers from this and have outdated 'latest' versions showing on their github page.

1

The short answer is.....

NO, you do not have to use the repo version number as a "release title" at GitHub! In fact it is bad practice! I recommend this format instead for your GitHib release title:

MySoftwareTitle v3.2

I will tell you why.....read on if you like...


How GitHub Releases, Tags, and Titles Work

I hope my answer explains how GitHub release naming conventions work, because there is no documentation at GitHub explaining this. None of the users above were able to answer the question in a simple way that makes sense, either.

What is a "repo" and a "release"?

A Git "repo" or "repository" is the original Git code base that you can view, code into, commit to, etc. This repo code is both a Git and GitHub term, which both use. You generally have a "local repo" on your local computer and one called a "remote repo" somewhere else. (Sorry, but Git nerds consistently assume everyone knows this. Most people do not!) In a company the remote repo is usually on a server somewhere in the network. In the "GitHub World" that "remote repo" is on the World Wide Web. Your "local repo" stores some files inside your .git folder that track the connection to the remote GitHub repo, so the two are locked in a dance. But they are not automatically in sync. nor are changes shared between them without you doing so. (That is a different topic you can research under "Git" online.)

A GitHub "release" is the same code as above, but with extra binaries, notes, and other goodies you can add that allow people to use your software and not add to it like a Git "repo" would above. Releases are exclusive to GitHub and something they dreamed up. It is not a Git term, nor a "repo". It is a new copy of your files that is completed software to be used. It has nothing to do with Git! Think of a release as the packaged software version of your repository at GitHub. It could be just some text files, DLL libraries, HTML, CSS, JavaScript, or a fully compiled software suite with documentation, binaries, etc.

How Do Releases Work at GitHub?

When you are ready to create a "release" at GitHub, you are creating a finished GitHub version of your repository code, not a Git repo, branch, etc. In other words, you are packaging up your "repo" code base into a GitHub zipped up package you can share with users online in a version of that code that is ready to be installed by users online and used, as is, with no Git repo connection to that code!

When you create your release, you are first asked to assign a "tag". But you will notice in GitHub there is a "dropdown" select list. This list pulls all "tags" from your repo you may have added to the code, like "v1.0", v2.3", "v3.1", etc. But you may not have used "tags" in your Git code. So they are offering you the option to pull tags from your repo Git code....or...just create one JUST for the "release" package. Confused yet? I was.

How Do Tags Work at GitHub?

When you save "repos" in any plain Git project (not GitHub) you can add optional TAGS to your code when you commit, merge, fork, etc that identify specific points in your code when saved in Git. For example, you could merge a large branch during a pull request and add "v2.0" as a tag in the code. "Tags" in the Git world are used like bookmarks with messages that mark important updates or changes in the history of your code. GitHub is hoping you are doing that and are trying to pull those into the release as markers of how your repo code base maps back to each release you create on their platform. But a "tag" is a Git feature, not a GitHub feature.

So, if you did not have "tags" in your repo, you must now create one. Traditionally, GitHub asked you to use a special convention using versioning like that shown above ("v1.0"). So they recommend you do that. But that has nothing to do with "releases". It is simply how Git sorts versioning "tags" and parses them. But staying with convention you help Git, not GitHub, except in parts of pages where GitHub shows sorted release numbers. But you do not have to use Git's or GitHub's tag/version number convention. Just because a community demands it doesn't mean it is a good system. In fact it is not! So use whatever convention you like. Just stick with a consistent one and remember it is simply being used for sorting release and repo code change points.

How Do Titles Work at GitHub?

Lastly, when you create a release, GitHub asks you for a TITLE. I could not understand the relationship with "tags" to "titles", version numbers, or to "repo title", etc. Does GitHub concatenate the "tag" version number with the "title", replace the "title" with the "tag", etc? No clue....

It turns out a "title" like a "tag" is just some text you give to your "release" and has nothing to do with the original repo title, tags, Git versioning, etc.

So, when I made my release I created a simple title matching the name of my "repo title" and added a " " space after it with my tag's version number typed again ("v2.0") after it. This release title is what GitHub will also assign to the website release name but also to the zipped download file name as well. That is why it is good practice to give your release a full text name with a version number at the end. Make sense?

So, GitHub does not write over your "title" or add the "tag" onto the end of your release title, as I thought. Using my title system, your title now has both the name of the software and the version to match the tag. This allows your release to me identified on millions of desktops but also include the version number at the end for sorting.

Other kids like to use kooky acronyms, but not everyone knows what those mean. DO NOT use cryptic acronyms, dates, version numbers, proprietary Git console commands and truncated terminology, as most people will get confused! So avoid those.

Note that the Git "tag" you assigned remains a separate value used elsewhere with GitHub for sorting and in your original repo code, so is good practice. It allows GitHub releases to map back your growing list of "releases" with specific commit and pointers in your evolving online remote repo code base.

Is my "Repo Name" the same as my "Release Title"?

They are NOT the same! But they can be if you like. What if my repo is called "ABC" but my software is actually "DEF", but has some "ABC" code inside it? That is fine too! Just remember, the "tag" system does map your release to a saved pointer in your Git remote Repo. The Title does not. But at the end of the day, it does not matter what you name your release. The repo title connection to it is meaningless now, as far as code or Git goes. But as I mentioned above, its much EASIER to match your release title to your repo title, exactly, then paste in at the end your matching version number to match, as well. This makes understanding each release and its relationship to the repo code much easier over time! So write a full title for every release!

GitHub Release "BEST PRACTICES" SUMMARY

  1. Try and add "tags" in your repo code on a regular basis as you complete finished points in the project and set a standard version number like "v1.0.0.0". Use a truncated version for simple projects, like "v2.1". These will then appear magically in your release tag list and allow GitHub releases to sync with Git tags.

  2. Now when you create your GitHub release, your tags with version numbers will now appear in the tags list of the release page to choose from. Sorry they didn't bother to tell you this! However....it is Ok to NOT use Git tags at all and simply make up your own tags. I recommend version numbers since GitHub will add these back into your repository code. But that text can be anything, not just release version numbers!

  3. Now type a nice release title that includes the name of your repo in it, or at least a software name that is unique to your project. Your GitHub release "title" can be anything you like! I recommend it match the name of your GitHub repo project, however. Just do not use cryptic, hungarian-notated, truncated acronyms like kids use today. That just creates mass confusion and a mess. Give your release name the software's full name so users know what it is, then add a space and then the tag version used above at the end. GitHub will now create your title as so in the release file name the user downloads to your computer as so. Below is what the download file name will become:

The Release Title you typed at GitHub: "MySoftwareTitle v3.2"

Your Release Title on the download file becomes this: "MySoftwareTitle-v3.2"

  1. GitHub will always place the latest release first in the list of releases associated with your repo. These releases are located to the right in the release section of your GitHub repository homepage. They always list the latest release first in the list, regardless of whatever text title you typed. So that is why your release title should have the name of the repo or software first followed by the version number to match whatever tag version text you used in the repo. If someone wants to dig for earlier releases they can click a link and see them listed newest to oldest with the added version numbers added at the end of the title.

Easy! Everyone now knows what the heck they downloaded from your GitHub page.

Peace

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.