What is the reason to use release version as a release title on GitHub?
It looks like this
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
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.
This is a larger screenshot of the actual page you found.
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.
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...
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
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.
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!
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"
Easy! Everyone now knows what the heck they downloaded from your GitHub page.
Peace
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.
