Package Immutability
Status: Reviewing
With Package Signing, we have two primary goals: Package Integrity and Package Authenticity
The package signing blog post calls out several key design principles - this spec focuses on Package Immutability.
The discussion around this spec is tracked here - Package Immutability #5917
To guarantee the integrity of a package, the package contents must not change from the time it was authored and signed to when a developer consumes it i.e. the package contents must be immutable, this includes the nuspec. Editing the package metadata results in changes to the nuspec, invalidating existing signatures. Thus, editing package metadata violates the key design principle - Package Immutability.
On NuGet.org, there are two ways you can edit the package metadata -
- Verify stage of the package upload workflow
- Edit package button on a published package
To adhere to the design principle of package immutability, the the ability to edit package metadata will be phased out.
The users will be able to edit package metadata but will see a banner which calls out our recommendation of not editing a package after it has been authored and point to a Read More link that explains the reasoning for this recommendation.
Q. Why do you recommend uploading a new package for making changes to package metadata?
A. NuGet will be implementing package signing. A design principle of package signing is that signed package content must be immutable, which includes the nuspec. Editing the package metadata results in changes to the nuspec, invalidating existing signatures. We recommend modifying existing workflows to not require editing the package metadata after the package has been created.
If you upload a signed package, the package metadata cannot be edited on NuGet.org i.e. all fields will be read-only at the verify package step, and no edit option for published packages. For unsigned packages, users will see the warning banner, but be able to edit the package metadata until next phase.
For example, I have 3 packages, and one of them -netstandard1.4_lib is signed, editing metadata for this package will be disabled.
- Once the package signing feature goes live, the Verify package step of the package upload workflow on NuGet.org will be made read-only. The page is merely to validate the information is accurate. If not, the user must cancel the upload operation, make the edits in the nuspec, and upload the package created using the updated nuspec.
- For published packages, the edit button will be removed from the package page on NuGet.org.
Note - Users will still be able to choose the package visibility option at the verify step of the upload.
Q. Why do you require uploading a new package for making changes to package metadata?
A NuGet requires all packages to be signed. A design principle of package signing is that signed package content must be immutable, which includes the nuspec. Editing the package metadata results in changes to the nuspec, invalidating existing signatures. We recommend modifying existing workflows to not require editing the package metadata after the package has been created.