4.7 KiB
4.7 KiB
NuGet Package Best Practices Review
✅ Implemented
Package Metadata
- ✅ Package ID, version, authors, and description configured
- ✅ Package tags for discoverability
- ✅ Repository URL and project URL
- ✅ MIT License specified
- ✅ README.md included in package
- ✅ Copyright information
Build Configuration
- ✅ Symbol packages (snupkg) for debugging support
- ✅ Source link for debugging into NuGet package
- ✅ .NET Analyzers enabled
- ✅ Code style enforcement in build
- ✅ XML documentation generation (from Directory.Build.props)
- ✅ Nullable reference types enabled
- ✅ Updated to .NET 9.0 (latest LTS)
Code Quality
- ✅ ISqlBreakdown interface for polymorphic usage
- ✅ Consistent inheritance hierarchy (all breakdowns inherit from SqlBreakdownBase)
- ✅ Parse/TryParse pattern across all breakdown classes
- ✅ Proper XML documentation on public APIs
- ✅ EditorConfig for consistent code style
- ✅ Serialization support with [Serializable] attributes
🚨 Critical Actions Required
1. Remove Duplicate Classes
IMMEDIATE ACTION: Delete these obsolete folders containing duplicate QueryBreakdown classes:
Strata.SqlTools/SqlServer/
Strata.SqlTools/Snowflake/
These are OLD versions that don't inherit from SqlBreakdownBase and conflict with:
Strata.SqlTools/Breakdowns/SqlServer/
Strata.SqlTools/Breakdowns/Snowflake/
Impact: Having two different QueryBreakdown classes in the same package will cause:
- Namespace confusion for consumers
- Compilation ambiguity errors
- Breaking changes if users accidentally use the wrong one
2. Review Public API Surface
Before publishing, verify that all public classes in these namespaces are intended for public consumption:
Strata.SqlTools.Breakdowns.SqlServerStrata.SqlTools.Breakdowns.SnowflakeStrata.SqlTools.InterfacesStrata.SqlTools.ExpressionsStrata.SqlTools.Utilities
Consider making internal classes/methods truly internal if they're implementation details.
📋 Recommended Improvements
Package Enhancements
-
Add Package Icon (Optional but recommended)
<PackageIcon>icon.png</PackageIcon>Add a 128x128 PNG icon to the project root
-
Add Release Notes File (Optional) Consider maintaining a CHANGELOG.md for version tracking
-
Consider Multi-Targeting (Optional) If you need to support older frameworks:
<TargetFrameworks>net6.0;net8.0</TargetFrameworks>
Dependency Review
- System.Data.SqlClient (4.8.6): Consider if you actually need this dependency or if you can make it optional
- Many users may only need the parser/builder functionality without actual SQL execution
- Consider:
<PackageReference Include="System.Data.SqlClient" Version="4.8.6" Condition="..." />
Versioning Strategy
- SemVer 2.0: Follow semantic versioning (Major.Minor.Patch)
- Major: Breaking API changes
- Minor: New features, backward compatible
- Patch: Bug fixes
- Consider using MinVer, GitVersion, or Nerdbank.GitVersioning for automatic version management
Testing & Quality
- API Compatibility: Use Microsoft.DotNet.ApiCompat to ensure no breaking changes between versions
- Benchmark Tests: Consider adding BenchmarkDotNet for performance regression testing
- Code Coverage: Add code coverage reporting (Coverlet)
📦 Publishing Checklist
Before publishing to NuGet.org:
- Delete duplicate SqlServer/Snowflake folders
- Verify all public APIs have XML documentation
- Run full test suite and ensure 100% pass rate
- Review breaking changes since last version
- Update version number according to SemVer
- Update PackageReleaseNotes with changes
- Test package installation in a clean project
- Validate package contents:
dotnet packthen inspect .nupkg - Sign assemblies (if required by your organization)
- Push symbols to symbol server for debugging support
🔧 Build Commands
Local Pack
dotnet pack src/Strata.SqlTools/Strata.SqlTools.csproj -c Release -o ./nupkg
Validate Package
dotnet tool install -g dotnet-validate
dotnet validate package nupkg/Strata.SqlTools.1.0.0.nupkg
Publish to NuGet.org
dotnet nuget push nupkg/Strata.SqlTools.1.0.0.nupkg --api-key YOUR_API_KEY --source https://api.nuget.org/v3/index.json