Do I have to update project version when only README has changed on GitHub?

Question

I'm editing one of my open-source projects on GitHub and I want to replace link (pointing to a demo) in README.md.

Do I have to update library version every time I introduce some minor changes to the README file or documentation (without any actual code changes)?

What is the community accepted practice?

If it's important, I'm using Bower to distribute my package and SemVer as a versioning system.

Answer 1

The README file is part of your codebase. It should describe the current (= in current commit) state of the code. A developer might read it outside GitHub's environment, e.g. from the node_modules directory on their hard drive, expecting it is up to date.

Therefore I would recommend to release a new version when the README changes.

It will usually result in just a patch number increase. But remember that when marking something as deprecated one must release a new minor version (paragraph 7 in SemVer v2.0.0).

If you plan to do really a lot of changes there are two ways to avoid releasing too often:

• Make changes in a branch. Merge to master here and there, release a new patch version.
• Move the documentation (or a part of it) somewhere else. GitHub Wiki or a simple webpage, e.g. using GitHub Pages, could come in handy.

Answer 2

You could include, as library version, the content of of git describe --all --long, as described in How can I get the Git build number and embed it in a file? (using git describe).

That way, you get the latest tag, plus the number of (small) commits you did since that tag.
That means:

• you don't have to put a new tag if you don't want to
• but you still keep an exact reference the the version of your repo which was used for delivering your app.