Package Immutability
Status: Implemented
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.
- 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 only allow editing the Documentation for the package, other fields will be removed and will no longer be available for editing from this page.
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.