How do I make a breaking change to a Nuget package?

Question

My apologies if some details here are deliberately vague, I don't want to get side-tracked by the specifics of the language, frameworks, third-party API, etc.

Some months ago, I developed some code to ease working with a specific third-party API. As the code seemed to be something that I, even if no-one else, would use again, I published it as a Nuget package.

When I wrote it, I was working within a specific web framework, and as the code needed some configuration before it could be used, I used the web framework's configuration methods to get the settings. I knew that this would prevent the package from being used with other frameworks, but I wasn't sure how else to do it at the time.

Now I've found out how I should have done the configuration, I want to change the code to do it that way, as it will open it up to being used from a much wider range of (web and non-web) frameworks.

This wouldn't be a problem, except that for some reason I don't understand, my Nuget package has had over 1500 downloads. Obviously that doesn't in any way translate into 1500 usages, but it does make me think that other people are using the package. If I introduce this change, it's going to break their code. Obviously, I have no way of knowing who has downloaded the package, and who (if anyone) is actually using it.

The main problem is that it's not going to show up as a compiler error, that would be OK (if a little anti-social), as it would be obvious that something had changed. The code will still compile and run, but will throw an exception when it tries to access the third-party API, as the settings will not have been set. If the consumer of my package upgrades to the new version, and tests everything, then they will find the problem, and (hopefully) work out what happened.

Realistically however, it's very likely that they may not test everything, and just deploy. I don't really want to be responsible for someone else's production code breaking.

I've seen suggestions about producing MyPackage.V2 and so on, but I'm not sure that's a line I really want to go down. I don't anticipate making this sort of change again, and would prefer to keep just the single package. It's not like this is an enterprise package that will change many times. I doubt I would ever need to do much to it again.

Anyone able to suggest what I do? I should point out that I published the package (and made the code open source) on the understanding that it is presented as-is, with no guarantees, but I still feel bad about doing something that I know will cause problems.

Any advice would be welcome.

Answer 1

Vincent Savard mentioned semantic versioning in a comment on your question. While semantic versioning is not a magical fix, it does provide a means to communicate that a breaking change has been made. You can visit the link in my answer for more information, but here is a summary of semantic versioning, then I can expand on how this helps solve your problem.

A semantic version number is in the form of n.n.n.n where the last segment is optional. At minimum, semantic version numbers need 3 segments (e.g. 1.8.5).

1. The first segment 1 is considered the major version. Increment this number when your NuGet package introduces breaking changes.
2. The second segment 8 is considered the minor version. Increment this number when you introduce a new feature and all pre-existing behavior continues working.
3. The third segment 5 is the patch number. Increment this if you fix a bug, but do not introduce any new features. All pre-existing behavior should continue to work (including the behavior that was technically "broken" in the previous version).

In your case, if your version was 1.0.0 then increment the major version of the NuGet package to 2.0.0. The increase in major version will inform most people that breaking changes have been introduced.

Some additional things you can do that help ease the transition:

• Include a change log text file in your repo that explains the breaking change.
• Configure the NuGet package with a project URL, probably to your GitHub repository.
  • The GitHub repository should have a ReadMe.md file which outlines usage and upgrade guidelines. GitHub will render the markdown file as HTML.
• Add a "readme" section to your NuGet package landing page.
  • More info: https://devblogs.microsoft.com/nuget/add-a-readme-to-your-nuget-package/

Basically you need to include information about the breaking changes and outline what code should be changed to use the new version. There are a variety of ways to publish this information online. Choose the way that works best with the tools you have.