Nuspec schema update policy

Nov 1, 2011 at 8:12 PM


I am writing to you all as a follow up on a recent discussion on Twitter with @hhariri about NuGet <-> SymbolSource compatibility issues. This is a problem that happened before already and is always caused by nuspec schema changes. So far I was convinced that nuspec is backwards compatible, i.e. you can read a 1.4 package with 1.5. In that case, we would only need to update NuGet.Core on SymbolSource any time a new version is released. This is still sometimes tricky, because the releases happen without notice, but manageable. However, from the issue @hhariri raised ( it seems that it could be harder, as packages generated in 1.4 fail to read in 1.5.

I would like to ask your opinion on how we should handle these kind of interoperability issues in a mixed-ownership environment. I suppose this concerns not only SymbolSource, but actually anyone that hosts their own feed with NuGet.Server or

My questions:

1. What's up with the lack of backward compatability? How about introducing a nuspec version number or consistently requiring an XML schema declaration?

2. How can we ensure better communication about planned changes and updates?

3. Could we setup a procedure to get a heads up on pending releases? Like "hey guys, here's the NuGet.Core for nuget.exe that we'll publish for selfupdate in 5 minutes, update your service".


Nov 1, 2011 at 10:06 PM

We always maintain backwards compabitility with regards to reading packages generated by earlier versions of NuGet. You said "packages generated in 1.4 fail to read in 1.5". Can you elaborate on this? Wat packagesare broken? Can you share the packages?

I don't quite understand the issue #1687 that hhariri raised. I always feel very frustrated when people file a bug by jumping right into describing their problems without any concrete repro steps. Please update the bug with concrete repro steps.

Nov 1, 2011 at 10:08 PM

Phil should be able to answer 2 and 3, but for the first one:

We haven't changed anything in our nuspec that breaks backward compatibility. If we did that, we would be unable to consume packages created via older versions of NuGet. Schema versions in the nuspec inside the package are generated based on the lowest compatible version. We use that to warn users if they are using an unrecognized schema. However I must admit we don't do a good job other advertising schema changes or publishing updated nuspec files anywhere outside the source control.

It's definitely a bug that a package created using an older version can no longer be read, but that's certainly not intentional.

Nov 2, 2011 at 12:22 AM

I'm sorry, I don't have example packages to reproduce this, only hhariri's statement... I hope he'll join in to elaborate :) Personally I'm more after answers to questions 2 and 3 :)

Nov 2, 2011 at 7:29 AM
Edited Nov 2, 2011 at 7:37 AM


I'm sorry you feel frustrated, but usually people filing a bug do describe *their* problem. I filed this issue because David Ebbo asked me to and as pointed out on the issue, at the time we were having problems with TeamCity server and then yesterday we were upgrading it so it wasn't accessible to provide the full log of the problem. Now it is available and I've added the log errors.


First time I mentioned this on Twitter, I was told that it was due to schema changes. As you can understand, I don't know the internals of NuGet so I cannot confirm, thus these discussions and thus filing an issue. Maybe it's a bug in nuget, maybe it's a bug with symbolsource, maybe it's not even a bug, which will be great for everyone. However, feeling *frustrated* isn't really going to help anyone is it?

Nov 2, 2011 at 11:56 AM

Now that I was able to have a look at the log, it's clear that this particular case was an issue on the SymbolSource side. It's probably unrelated with the NuGet version mismatch. The server had trouble processing the package as a ZIP file which manifests itself as "System.Exception: Unable to find part of path 'lib/net40' before 'net40'.". We are aware of this issue and are trying to fix it, unfortunately it proves to be a bit undeterministic. I can only say sorry from our end for now.

You can probably close the bug #1687 now. 

The second part of my original post is still on the table, however :)

Nov 2, 2011 at 12:00 PM



Thanks for the update. I've requested also the bug to be closed.