Wildcard versioning consideration for .NET PackageReference

Application Versioning

Versioning an application using the x.y.z format, commonly known as Semantic Versioning (SemVer), Semantic Versioning uses a three-part version number: MAJOR.MINOR.PATCH.

Semantic Versioning Rules

1. MAJOR version (x): Incremented for incompatible changes that may break backward compatibility or when you introduce significant new features that may require users to adjust their code or configurations.

2. MINOR version (y): Incremented for backward-compatible functionality enhancements, add new features or improvements in a backward-compatible. This allows to upgrade with less of breaking existing functionality.

3. PATCH version (z): Incremented for backward-compatible bug fixes, performance improvements, or other small changes that don't add new features or change existing ones.

Additional Considerations

1. Pre-release Versions: Indicated by appending a hyphen and identifier (e.g., 1.0.0-alpha, 1.0.0-beta, 1.0.0-rc.1) to indicate that the version is unstable and may change before the final release.

2. Build Metadata: Indicated by appending a plus sign and a series of identifiers or information about the build, such as build date, commit hash, etc. (e.g., 1.0.0+20240529144700), This metadata is ignored when determining version precedence.

Best Practices

1. Start with 0.y.z for Initial Development: Use 0.y.z versions for initial development. Anything may change at any time, and the public API should not be considered stable. (Example: 0.1.0, 0.2.0).

2. Release 1.0.0 When Stable: Once the project is ready for general use and has a stable API, release 1.0.0.

3. Consistent Incrementing: Follow the increment rules consistently to avoid confusion and maintain clarity on the state of your application.

   • MAJOR: 1.0.0 -> 2.0.0 for breaking changes.
   • MINOR: 1.1.0 -> 1.2.0 for new features.
   • PATCH: 1.1.1 -> 1.1.2 for bug fixes, typo, add documents.

4. Document Changes: Maintain a changelog to document what changes have been made in each version. This helps users understand what has been updated, added, fixed, or changed.

5. Automated Versioning: Use tools and CI/CD pipelines to automate versioning based on commit messages, tags, or branches.

Package Reference

In .NET Application, managing dependencies using PackageReference in the project file (.csproj) is a common practice to specify the versions for a dependency.

Wildcard Versioning

Wildcard versioning allows you to specify a range of acceptable versions for a dependency, giving application flexibility in which versions it can use.

Wildcard Patterns

• 1.0.*: Allows any version that matches 1.0.x, where x is any number.

  • Example: 1.0.0, 1.0.1, 1.0.2, etc.
  • Behavior: When using 1.0.*, project will use the latest available version that matches 1.0.x.

• 1.*: Allows any version that matches 1.x.x, where x is any number.

  • Example: 1.0.0, 1.1.0, 1.2.3, etc.
  • Behavior: When using 1.*, project will use the latest available version that matches 1.x.x.

• *: Allows any version.

  • Behavior: When using *, project will use the latest available version regardless of the major, minor, or patch version.

Example of PackageReference

In the .csproj file, to specify a package dependency with a wildcard version:

<ItemGroup>
  <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="8.0.*" />
</ItemGroup>

In this example, any version of Microsoft.Extensions.DependencyInjection that matches 8.0.x will be acceptable, and will use the latest available version in the 8.0 series.

Pros and Cons

Pros

1. Flexibility in Updates:

   • Wildcard versioning allows project to automatically update to the latest version within the specified range. This reduces the need for manual updates and ensures that you benefit from the latest improvements and bug fixes without additional effort.

2. Immediate Access to Fixes and Improvements:

   • By using wildcard versioning, you can receive bug fixes and performance improvements as soon as they are released. This helps keep application secure and up-to-date with minimal delay.

3. Reduced Maintenance Overhead:

   • With wildcard versioning, you don't have to frequently update the dependency versions in project file. This simplifies the maintenance process and reduces the workload on developers.

Cons

1. Potential for Compatibility Issues:

   • Automatically updating to the latest version within a range can introduce compatibility issues. If a new version contains changes that affect application, it might lead to unexpected behavior or bugs.

2. Unpredictable Builds:

   • Wildcard versioning can lead to inconsistencies between different builds or environments if the latest version changes between deployments. This can make it harder to replicate and debug issues.

3. Security Risks:

   • While you can quickly adopt security patches, you might also introduce new vulnerabilities with automatic updates. It's important to review and test new versions thoroughly to ensure they do not compromise application's security.

4. Testing Overhead:

   • Each time a new version is pulled in by the wildcard, it needs to be thoroughly tested to ensure it does not break existing functionality. This requires a robust testing framework and continuous integration setup.

5. Lack of Control:

   • Wildcard versioning reduces control over which versions are used in your application. You might end up using versions with undesired changes or bugs that could have been avoided with more specific versioning.

Consideration

Pain Point with Wildcard Versioning

I encountered an issue where some dependencies from open-source projects did not adhere to standard versioning practices. These dependencies occasionally introduced breaking changes in patch versions, despite the expectation that patch versions should be backward-compatible. This caused compilation and runtime issues that were difficult to predict and resolve.

Using x.* wildcard versioning led to scenarios where minor version updates introduced breaking changes. These breaking changes affected the stability of my application, resulting in runtime errors. Since the minor updates were supposed to be backward-compatible, this behavior was unexpected and problematic.

While we had automated end-to-end testing in place, not all features were fully covered. Some changes introduced by new dependency versions were not detected by our tests. Additionally, manual testing was infrequent, leading to silent issues that only became apparent in production. This lack of comprehensive testing allowed significant problems to slip through unnoticed.

Considerations and Solutions

Following these pain points, I decided to switch to using x.y.* for versioning dependencies. This approach narrows the range of acceptable updates to only patch versions within a specific minor version, reducing the likely of unexpected breaking changes.

1. Trustworthy Dependencies

Prioritize dependencies that are maintained by a strong community or first-party contributors. Trusted sources are more likely to follow semantic versioning strictly, ensuring that minor versions remain backward-compatible.

2. Increased Testing

Enhance automated testing to cover more features and edge cases. Ensure that critical paths and integrations are thoroughly tested. This reduces the risk of undetected issues when dependencies are updated.

3. Manual Testing Practices

Sometimes it is difficult to automate end-to-end testing for certain scenarios. In such cases, schedule regular manual testing sessions to catch issues that automated tests might miss. This adds an extra layer of assurance that the application functions correctly with new dependency versions.

Conclusion

Wildcard versioning provides significant flexibility and convenience by automating updates and reducing maintenance efforts. it also introduces risks related to compatibility, security, and control, which require careful management and robust testing practices to mitigate.