4

Using Semantic Versioning, I have a product that is version 1.0.0. It has a configuration file entry shipped with the product that specifies an operation timeout value:

myTimeout=1000

I need to change this configuration value. Is this a MINOR or PATCH increment? It's not a bug fix, but it's not really introducing a new feature, in my current opinion.

EDIT: A few interesting points raised - seems like all things in computing that there are always edge-cases and no solution fits all.

  • So you are changing 1000 to another value? If there's no bug, why's it changing? – David Arno Dec 8 '16 at 14:29
  • It's changing not due to a bug. That's all that matters. Maybe i'm in receipt of slower hardware on the server side so I need to increase the timeout value. – thehowler Dec 8 '16 at 14:59
  • 2
    Oh but it does matter. If it's changing because you have found that eg 500 doesn't cause problems, but provides significant improvement in performance, then it's a feature enhancement and so I'd change the minor number. If 1000 is causing problems and another value solves them, then it is a bug fix, so I'd change the patch number, etc. – David Arno Dec 8 '16 at 15:05
  • 1
    Are you planning to change the version number every time a customer decides a different timeout value would be more effective for them and goes and changes it by themselves without telling you? – 8bittree Dec 8 '16 at 15:31
  • 1
    In another words. If the property would be a entry in the db. Would you change the version every time the value is modified? – Laiv Dec 8 '16 at 18:06
6

If you need to distribute new copies of the software, then bump the patch version. Your changelog would be

  • Changed default value of myTimeout configuration to 1000
5

Do you even need a version change for a configuration entry? The whole point of version numbers is to distinguish software changes, not data changes.

If you do insist on a version change, either because your deployment process requires it or you just want to track it, I would use the lowest possible granularity (a patch number or build number).

  • How does your question relate to upgrading an application's dependencies, as opposed to a configuration file? The versioned consuming application hasn't had its code changed, yet Sem Ver states that this should involve a version bump. As an interesting aside, what happens if a pure refactoring has taken place so, in essence, no bugs have been fixed and new functionality has been introduced. Hmm.. – thehowler Dec 8 '16 at 19:15
  • 2
    A refactoring is a code change; I would expect a version bump. Sem Ver is just a guideline; ultimately you have to do what makes the most sense for your shop. The most important part of Sem Ver, from my perspective as a user or consumer, is that I would expect the API's to remain stable on a minor version change. If you change anything that affects me as a user, I would expect a version bump. – Robert Harvey Dec 8 '16 at 19:21
  • makes sense and good reasoning – thehowler Dec 8 '16 at 19:31
  • You would need a version bump if the configuration change fixed an issue identified by users. If this timeout resolves a problem, then a version bump makes sense. – Greg Burghardt Dec 9 '16 at 1:27
1

Semver applies to the versioning of APIs and libraries. The whole point of Semver is that you can immediately see that you can switch from an old API version x.y.a to a new version x.z.b, provided y ≤ z. That is: Semver standardizes a notation for API compatibility.

This means Semver is not immediately applicable for applications or other products that don't offer an API. For example using Semver for a web application would be utterly ridiculous; a single incrementing deployment number is sufficient if a version number is needed.

As Ewan and 8bittree point out, the point of config files is that they can be changed independently of the software.

  • If the API user changes the configuration file, the API version should not change – the user might update a deployment number, though.
  • If the API provider creates a new release with an updated default configuration file, that release needs a new version. Note that updated defaults do not affect existing users in any way, since they already have a configuration file – or would your upgrade process overwrite their customizations?

Assuming that you do have an API that merits a semantic version number, and that changing the default config file requires a new release, and that the updated defaults don't affect existing users with their own config file, then you should increment the patch number. Why?

  • The change is relevant for users. They need to be able to distinguish versions that have the new default in the configuration file. This means the version string has to change.
  • The major release number should only be incremented for backwards-incompatible changes. This is not the case here.
  • The minor releas number should only be incremented when adding new functionality in a backwards-compatible manner. You are not adding new behaviour.
  • The build metadata should be ignored when comparing versions, so it's not the place to signify changes.
  • Likewise, marking this as a pre-release version does not help here.
  • Therefore: By exclusion, there's no other suitable place except for the patch number to signify the configuration default change. That patch levels are intended for bug fixes should not hinder you here, it's just that bug fixes are the most common kind of change that doesn't add or change documented behaviour.
0

Generally with config file changes:

The version of the software should not change.

The version of the deployment should change.

since you are bundling the config file with the software, maybe you could version it separately?

  • Not sure why I'd want to version deployments independently from source code. – thehowler Dec 8 '16 at 15:00
  • because a deployment of the same version of the software is often different in configuration when you deploy it – Ewan Dec 8 '16 at 15:11
  • @thehowler I think Ewan is pointing to a possible tracking (versioning) of the configurations deployed. It could make sense if you are executing load tests looking for the optimal configuration. – Laiv Dec 8 '16 at 18:12
-1

Versioning based on a value in a config file seems rather ridiculous. The purpose of putting things into config files is usually so that the end user can change them as needed without waiting on you, and so that you don't have to maintain a unique application for every single customer.

As I mentioned in the comments, are you really planning to bump the version number every time a customer changes their configuration? That's going to be difficult if the customer doesn't tell you about it. You could have the application phone home with any changes, but privacy and security advocates are not going to be happy about that, not to mention, that's extra work for you to set up.

And if you don't update the version number with each change, then it doesn't really tell you anything about the configuration values, does it? If you're trying to debug a problem they're having, you're probably going to have to look at the current configuration, not what it was for five minutes after they installed a year ago.


If you really, really want to add some noise to your version number, this seems like the most relevant section of the SemVer FAQ:

What should I do if I update my own dependencies without changing the public API?

That would be considered compatible since it does not affect the public API. Software that explicitly depends on the same dependencies as your package should have their own dependency specifications and the author will notice any conflicts. Determining whether the change is a patch level or minor level modification depends on whether you updated your dependencies in order to fix a bug or introduce new functionality. I would usually expect additional code for the latter instance, in which case it’s obviously a minor level increment.

(Emphasis mine)

Since there's no new code involved in this change, that would suggest a patch level increment.

  • 1
    The configuration is shipped as part of the product. This is an in-house so the customer is, essentially, the same entity as the solution provider. What other audited mechanism is available for configuration changes shipped as part of the application? Or, put another way, if the configuration happened to be in the same release as a code change I bet everyone would be OK with the code version number change "carrying" the config change with it. – thehowler Dec 8 '16 at 19:11
  • @thehowler Audited, and for just one customer who is also the provider? A simple VCS commit? – 8bittree Dec 8 '16 at 19:43
  • 1
    There is a huge difference between a customer changing a config value and the default value of a distribution changing. -1 – RubberDuck Dec 9 '16 at 0:22

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.