1

Currently, my repo contains application code and what I call non-functional files, which include deployment scripts, README file, build system requirements, dependencies etc. These files are released as part of each release so that other developers could completely rebuild the environment if needed.

My project follows SemVer versioning standard. When I update the application code, then versioning is clear.

But what if I update a README or a deployment script? Do I increment a PATCH version and make a new release? Or do I simply merge the changes into the trunk without incrementing the version and making a release? Trying to see if there is a canonical way of doing this...

3
  • 4
    You never want to have different release packages which have the same version number, even if the difference is only in documentation - because that can very easily create confusion. Each release should have a unique version number, even if it's just a difference in patch number.
    – Jesper
    May 4, 2023 at 13:18
  • Another option could be to include a date-time tag as part of SemVer for any builds which might produce an artefact but where you don't intend to bump a minor or patch number. For example: Major.Minor.Patch-20230405191842555 (based on 2023-04-05 19:18:42.555) -- this allows you to uniquely identify every built artefact as well as generating a unique tag/label for the build commit, without worrying about your version scheme). May 4, 2023 at 18:21
  • The problem is that Semver doesn't apply to applications. Even if it does, why would you bother everyone (company and consumers) with such non-functional changes? Why would I care if your app 1.1 was executed in an EC2 instance and 1.2 runs as 2 pods in some random Kubernetes cluster? Leave alone, bothering me with changes in a shell script that cleans workspaces after a build... Unless these assets (and info) matter to the consumer, why should you trigger a whole release process? Why should I feel the urgency to checkout changes in the new (coming from nowhere) version of the app?
    – Laiv
    May 16, 2023 at 11:49

4 Answers 4

2

My rule is that if it is included in the release package it causes a bump in version number.

So things like documentation or a fix in the installation script gets a patch release. If the file is read or in any way used by a third party it should probably be included in the release. And then it needs a bump in version number to be able to track the release version.

Changes to internal tools are not included in a release, so no increase in version. Things like test scripts, internal developer documentation etc.

I leave it to you to figure out what category your specific files fall into.

0

Yes.

As a simple practical matter if you build on every change and increment on every build, then there's no easy way to exclude arbitrary files.

If we are talking about some kind of large printed out manual, then I would expect it to have its own revision system and versioning. Separate from the code.

But these kind of small files you want to keep with the source code. You don't want to have a separate revision versioning system for them. Its arguable whether one is needed, but why not take the free one that comes with the code?

0

I guess, having read many readme files, manuals and overviews, and also read help files & faqs in various formats, html & text & chm, the answer is in the structures you create around the software.

Eg. An online download is usually packaged, and you can't update a readme or help or doc without repackaging which creates a different checksum or hash, which is regardless of what you would like, seen as a different version of the download file, even if you don't increment a version number or filename.

So, what websites usually do is have the download file versioned, and then have the readme or patch notes as an independent 'no versioned' file, and I guess they update the checksum or hash if the readme has that available. This allows the solution to be rapidly posted, and later any changes to disclosure or detail can be adjusted and improved.

What often occurs is that help files are put on the internet, and apps refer to help files, so the manuals and more comprehensive technical details are easily updated without ever needing to update the application or any complied downloads. You explicitly state that the bundled information is subject to change, and to seek and refer to the latest available online version.

Having used software for a reasonable time as a somewhat technical user who helps other often non-technical users, it's very annoying when you need internet access for faqs, docs, readme or help files, instructions, manuals and the like.

So I'd suggest you be as comprehensive as you can, version AND bundle those versioned files with the software in any downloads or distribution system, but internally, within the software, or on the homepage or download page where you describe it, have links to updated versions that can be improved independent of the already-published detail. I've even seen this (rarely) as 'google this' rather than a hyperlink, as maintaining URLs, even permalinks, over years or decades can be expensive and difficult and a security risk.

It's not uncommon to need to rush a release but not have complete documentation, though it's bad form, especially for free or low cost software, or software that has no margins until it's popularity improves, software that has intrinsic demand by virtue of being unique, bespoke or specific to a vertical that has a real demand. If you're making something for free, it's usually 'take it or leave it' and 'as is'.

Also, remember the FAQ is supposed to be questions asked of users. So you can't write the FAQ, until you get feedback and people actually start asking the question more than once, so they become 'frequently asked' and you actually get tired of answering them, and have answered them enough to be able to write a good answer.

Perhaps, imagine it from the perspective of the FAQ.

You are wanted, needed. So you are written 'in anticipation' from guesses the devs or other associates hint or suggest, or on experience. Then, you are weak, as you're not real. You're a fake faq. But at least you perhaps have some marginal value, as you help define or sent bounds or help with context, either directly or by what you omit.

Later, you get attention & are edited. Some parts of you are removed, then new parts added. As you become more valuable, you are adjusted and edited over and over again. and more often. You might find that comprehension is low for some of the answers or the questions in your body. So you're constantly massaged and tweaked and groomed, until you shine like you have a fresh coat and have had a really good summer.

From beginning to end, you, the FAQ, may undergo thousands of changes! Some of those might be by the devs, but often it's by sales personnel or assistants or volunteers or community champions.

Now, do you really need a version number? How about a date-stamped changelog if not a version?

The answer, probably is no. As you're an FAQ, likely on a website, indexed and a part of the marketing and sales, and the sets of text that help the software be understood and valued. You're not the software. You might frequently never even be needed until something fails or works unexpectedly well or poorly.

It's different if you're a manual, and it's an aircraft, or a vehicle, or I guess, high speed bicycles, such as lithium powered ebikes. These may have faqs, but will still need manuals which detail what the different hardware does, as they are human safety devices.

The legal aspects would be associated mostly with the manual, and they tend to be kept relatively simple and free of detail, because that creates legal risk. The more you put in a readme or a manual or a faq, the more mistakes you may make, or the greater the chance of misunderstanding.

So typically, for legal liability reasons, I guess manuals are a very different thing to readmes or faqs or guides. Perhaps this excludes quick-start guides for printers, which tend to be more IKEA-like, with pictures to again, hopefully reduce ambiguity and multiple meanings being a liability.

Ok, having strayed beyond the scope, to bring the answer back, you need to put more detail in on what the software purpose is, and what it's inputs and outputs are, and what connection it has to physical matter, and if that's related to human safety, or probably, given we're in an extinction event with climate change and rising seas from AGW and greenhouse gases, flora and fauna safety, particularly with respect to habitat preservation and climate migration options.

Even if you have a software licensing agreement that excludes liability or ownership of loss or damage, you still have an obligation to be respectful and considerate, and that means you need to anticipate what problems may occur, and try to in a premeditated way, reduce the chance that those problems in software become actual problems for people or matter or material goods. Everything can be misused or fail, so it's typical to engineer around that.

Good explanations and documentation that can be searched, indexed, skimmed, spidered, assessed by date, and I guess, now ingested and analyzed and quantified and regurgitated by AI, have broad value, often beyond the software that they are inspired by, or written to accompany.

0

It is useful to have the most minor version code changing every time anything is changed and the modified version has been released at least internally for testing (not all internal releases need to go into production). This makes bug reports much more consistent, some bugs may disappear or behave differently when running earlier or later versions of the code. A bug report should include this minor version.

Modifying deployment scripts may be quite a major change. Modifying documentation may be important change if the bug finally resolved to that the user have misunderstanding about the expected behavior of the program.

A marketing department may use officially completely different versioning because they have very different goals to achieve with the version numbers.

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