I'm trying to decide how consistently to apply Semantic Versioning to maintenance changes. I recently upgraded several GitHub Actions, which don't affect the library's runtime behavior, so a patch release felt unnecessary. However, I also updated dependencies such as Mermaid, whose internal parsing behavior could affect users even though I didn't change my own code. For consistency, I included both kinds of updates in a patch release and documented the CI upgrades in the changelog. Is that excessive or confusing for users, and where do you draw the line between changes that deserve a patch bump and changes that should remain unreleased or only appear in internal records?
4 Answers
The important question is whether consumers can use the new version without previously valid code breaking. A dependency update becomes potentially breaking when it changes behavior that your library exposes or relies on, especially if it can invalidate existing usage. In that case, follow the normal SemVer rules and use a major version for an incompatible change. A CI-only update that doesn't affect the built artifact or user workflow usually doesn't need a public version bump.
It helps to separate release policy from changelog policy. A workflow upgrade can be recorded under a CI or maintenance section without creating a package release. Dependency updates are worth a patch release when they affect the shipped artifact, runtime behavior, generated output, or supported environments. If they only improve development tooling, keeping them out of the public release history is perfectly reasonable.
For software that is continuously deployed, calendar-based versioning can be less awkward: every published build gets a version based on its release date, regardless of whether the change was code, dependencies, or CI. For a reusable library, though, SemVer is useful when interpreted by API compatibility rather than by the size or effort of the change. Either way, noting maintenance changes in the changelog is not silly if the section makes clear that they don't affect consumers.
Some teams simply issue a patch for every change because versions are cheap and it gives everyone a precise reference point. That can be a practical policy, but it isn't required by SemVer. API additions are minor only when backward compatible, and any change that breaks existing consumers is major; the size of the feature or whether the code feels 'different' isn't the deciding factor.
Exactly. A consistent patch-for-every-release policy can be useful operationally, but it should be described as a team convention rather than as what SemVer requires. The public changelog can also distinguish user-facing changes from internal maintenance.