0

Goal

I'm working on libraries published as nuget packages and I would like the version of those packages to update automatically based on the changes I make.

In other words, I would like something that automatically adjusts the major, minor, and patch numbers based on the changes of the API surface of the library.

This should be possible if we define the "public API" mentioned in the SemVer specs as the actual public API surface from the assembly (public classes, interfaces, structs, enums, delegates, protected methods, etc.).

Examples

Let's say the current version of a LibraryA is 1.0.0.

  • If I change the signature of a public method, the version should become 2.0.0.
  • If I add a new public class, the version should become 1.1.0.
  • If I change the implementation of a private class, the version should become 1.0.1.

Limitations (Edit)

Following amon's comment, I understand that behavioral changes can break compatibility. It is also unlikely that a tool could understand changes in behavior by comparing two assemblies.

I'm not looking for a perfect versioning solution. I think the API surface is a good start for an automated versioning system, especially considering that I have automated tests that validate behaviors.

Motivation

  • If it can be computed automatically, why should a human do it and potentially make mistakes?
  • In an open-source collaboration context, having a tool tell you the level of change a pull request brings can help organize contributions. e.g. Contributions that bring breaking changes can be combined overtime to produce 1 major release each year.

Sought Answers

Using an existing tool would be ideal, but I haven't found one that checks API surface yet.

If you know of a tool that does this, please let me know!

I know there are tools like GitVersion that compute a version number based on some metadata, but that metadata usually needs human input (like git tags, commit message, etc.), which is what I want to avoid.

Any other advice on how this could be custom-implemented is also welcome.

Thanks!

Improve this question
3
  • 5
    There are other ways to break compatibility than just changing the API surface. Behaviour can also change incompatibly. However, it is generally impossible to judge whether two behaviours are compatible (this runs straight into “halting problem” territory). At most, such an automated tool could suggest a minimum SemVer increment, e.g. flagging it as an error when a public method was removed without incrementing the major version.
    – amon
    May 14, 2022 at 6:10
  • 3
    There is a reason why this versioning scheme is called semantic versioning, not syntactic versioning.
    – Doc Brown
    May 14, 2022 at 7:42
  • @amon and there's a tool to do exactly that in php: Roave Backward Compatibility Check. I don't know if C# has any equivalent.
    – bdsl
    May 14, 2022 at 9:54

1 Answer 1

Reset to default
5

In the comments, amon is absolutely right that just changing the interfaces is insufficient to determine if behavior is backwards compatible. I find it highly unlikely that you would be able to build a static analysis tool that determines if code changes represent something that would cause the patch, minor, or major version field to change.

However, all is not lost. Although you may not be able to scan the code changes, you may be able to automate semantic versioning using your commit history if you use something like Conventional Commits. During your release process, you can scan the commit messages and increment the appropriate field based on the highly-structured format in commit messages.

Improve this answer

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