I'm trying to establish a consistent versioning and changelog policy for a library. I recently upgraded several GitHub Actions, including setup-go, CodeQL, Scorecard, and Docker Login, and initially felt those changes shouldn't qualify for a patch release because they don't alter the library's source code. However, I had recently bumped dependencies such as Mermaid, whose behavior can affect parsing and therefore potentially affect users, so I included those in a patch release for consistency. Is it reasonable to publish a patch version for CI-only changes, or should those updates stay out of the public changelog? How do you draw the line between maintenance changes that users should see and changes that are only useful for maintainers?
4 Answers
The main question is whether consumers can use the new version without breaking previously valid code. A dependency update only becomes a SemVer-major issue if its behavior changes how your library works and makes existing usage invalid. CI upgrades that don't affect the produced package generally don't require a release at all. Dependency changes that can affect runtime or parsing behavior are reasonable to record, usually as a patch when they remain backward compatible.
It can be useful to separate release-worthy changes from repository maintenance. Workflow-only updates could be placed under a CI or maintenance section and omitted from the versioned release notes, especially if they don't change the built artifact. If a workflow changes the build or publishing result, then treating it as a release-related change makes more sense.
For an application or internal project, SemVer may not provide much value. Calendar-based versions or a simple date/build identifier can make more sense when releases are primarily about when something was built. For a public library with independent downstream users, SemVer is more useful because the important signal is compatibility, not how large or interesting the code change was.
Some teams bump the patch number for every change because versions are cheap and the precise reference is convenient when debugging. That's a valid project policy, but it isn't the same as strict SemVer. Under SemVer, a patch release is for backward-compatible fixes; a new feature gets a minor version, and a breaking API or behavior change gets a major version. The size of the feature isn't what determines the bump.
That distinction works well for me too: document CI changes for maintainers, but don't create a package version unless the generated software or its behavior actually changes.