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.

  • 1
    Are you familiar with version schemes such as semantic versioning? There are also ways to try and ease the transition, e.g. keep the original API, but gradually introduce a new one that users can migrate to while still being able to upgrade their library without breaking changes. At that point, there's a trade off to make between the ease of implementation for the author of the library, and the ease of upgrading for the users of the library. May 18 at 13:02
  • @VincentSavard Not very. I'm a lone developer, and never really needed that sort of thing. I only published this as a Nuget package to make it easier for me to reuse. If anyone else wants to use, that's fine, but I've no experience with publishing APIs. I understand the concept of versioning, but don't see how I would use it to help here. My package has a version number, which has increased as I published new versions, but I don't know how this would help. Please could you elaborate? Thanks very much. May 18 at 13:05
  • Can you make it a setting or configuration parameter that requires being set in order to use the new functionality and if not does it the original way. And maybe comments or marking something as obsolete if not using the new setting. Without knowing all the details of your code don't know if that makes sense or not. May 18 at 13:39
  • @ScottMildenberger Not really. I did think of that, but one of the big problems with the way I originally did it, is that it has a dependency on the specific web framework. One of the reasons I want to do this change is to remove that dependency. May 18 at 14:05

1 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.

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.

  • Thanks for all of that, but I'm basically doing al that already. My concern is that other developers may be like me, and update without really looking at the version number and thinking "Hey, a major version number change, must check the project's ReadMe and see if anything broke." I'm not sure that anything you have suggested would really help for what I assume is the majority of developers. Thanks again. May 18 at 16:06
  • It is up to other people to pay attention to this sort of thing and read documentation. You, as the maintainer of this NuGet package, can only do so much. At some point the responsibility is on those developers to manage their application's dependencies. May 18 at 16:11
  • OK, sounds like I'm being a bit too cautious then. Maybe you could add that comment to your reply. Thanks again. May 18 at 16:32
  • 1
    I would suggest that in addition to updating the major version, you remove the methods which will break in the new version. Don't just throw exceptions. You want devs who blindly upgrade to get a compiler error, not a runtime error. This signals to them that they need to stay on the old version, or review your changes to see what broke and why.
    – Graham
    May 18 at 16:43
  • @Graham I like it! I was hoping not to have to change the methods, but it would certainly make it more obvious that there had been a breaking change. Thanks May 18 at 17:10

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.