Versioning: Where exactly in the code or repository should I write the version number?

Question

Right now I'm doing this:

1. Update the readme to include the new version number and what it does.
2. Commit the version number in git commit message (i.e git commit -m "1.2.1: this does that").
3. Push the repository.

Is this the proper way of doing it? I had a hunch that this is wrong, because this way I have no idea how to version the branches. Previously I'm almost always working directly in Master, because more often than not I'm working on a repository alone. I want to change this.

Edit: specifically I'm working on web apps where I have no compiled binaries.

Answer 1

Your code doesn't have a version. It's your compiled program which has a version.

Create the version number when you do the build and have a build step which tags the git repo at the point at which it pulled the source, with that version number

Answer 2

In most software systems, it is a good idea to put the version number in a place where the program itself can display it to anyone who needs to know it. That requires adding it to a code or resource file. Where exactly depends on the technology involved, and who the persons are who need to get informed.

For example, it may be the end user who shall be able to find out the number easily, so you need a function to display it to him. This way, a support hotline can ask users which version they currently use. Or it maybe just the administrative staff. Or in case there is only one installation of your web app, you can decide to keep the version number fully internal, since "support" may be able to check this one unique installation directly.

If your "readme" serves as changelog, then yes, the version number will also occur there (obviously, how would you otherwise make references to change descriptions)?

I have no idea how to version the branches

New version numbers are assigned for each release of your software, to "production" and/or "test" environment. You should not release from arbitrary branches, you release only from your "Master" branch or a special "Release" branch, from nowhere else. And if you have bugfix branches or feature branches in use, you either integrate them before deploying a release into "Release", or not.

Therefore, it is usually only important to mark the version in the repo inside the "Release" branch, exactly at the point in time when a new release is created. A standard tool for this are tags, but you may decide that for test releases a version number in a commit message may be enough. That is up to you and depends a lot on how your team worksin general and the kind of system you build.

So from an outside point of view, you create the illusion of changes applied to your system in a linear order, one after another, each group of changes with a higher version number. The exact version number which is written into the code files of a certain branch is usually unimportant and should not bother you.

Answer 3

You almost certainly want your version number to be somewhere in your source code (counting "source code" generously), so that your compiled / executable code knows its own version number - even to just be able to display it to a user. So if your program is version 2.1.4 then this should be somewhere in your source code.

On the other hand, as a developer, if I ask you eight months from now "can you give me the exact complete source files that went into 2.1.4", you'd want to be able to do that easily. You have two easy choices for that: Keep a backup of exactly those source files, quite independently of git, or use a tag in git. Tags make this very easy. Completely independent of branches, everything that is tagged you get back exactly.

The "backup" method isn't that bad if building a product relies on more things than just what's in git. You might have built 2.1.4 using version X of some library that isn't in git, and in eight months time your 2.1.4 sources don't work anymore because you updated the library to version Y, or you updated compilers. If being able to reproduce a version later exactly is essential then backing up sources and complete build system is not a bad idea.

Answer 4

I would add the version number to the repository (i.e. in git repositories this is called "create a tag" or "create a branch")

Answer 5

Things like Node.js have a package file which contains this information. Not bad. I work primarily in web and I use a changelog file. It is relatively trivial to programmatically pull the version from the changelog file and it can be easily done by using bash or something similar. Adding the changes is a normal part of my workflow so it's not too much of an additional burden.