134 lines
4.7 KiB
Markdown
134 lines
4.7 KiB
Markdown
# 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.SqlServer`
|
|
- `Strata.SqlTools.Breakdowns.Snowflake`
|
|
- `Strata.SqlTools.Interfaces`
|
|
- `Strata.SqlTools.Expressions`
|
|
- `Strata.SqlTools.Utilities`
|
|
|
|
Consider making internal classes/methods truly internal if they're implementation details.
|
|
|
|
## 📋 Recommended Improvements
|
|
|
|
### Package Enhancements
|
|
1. **Add Package Icon** (Optional but recommended)
|
|
```xml
|
|
<PackageIcon>icon.png</PackageIcon>
|
|
```
|
|
Add a 128x128 PNG icon to the project root
|
|
|
|
2. **Add Release Notes File** (Optional)
|
|
Consider maintaining a CHANGELOG.md for version tracking
|
|
|
|
3. **Consider Multi-Targeting** (Optional)
|
|
If you need to support older frameworks:
|
|
```xml
|
|
<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
|
|
1. **API Compatibility**: Use Microsoft.DotNet.ApiCompat to ensure no breaking changes between versions
|
|
2. **Benchmark Tests**: Consider adding BenchmarkDotNet for performance regression testing
|
|
3. **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 pack` then inspect .nupkg
|
|
- [ ] Sign assemblies (if required by your organization)
|
|
- [ ] Push symbols to symbol server for debugging support
|
|
|
|
## 🔧 Build Commands
|
|
|
|
### Local Pack
|
|
```powershell
|
|
dotnet pack src/Strata.SqlTools/Strata.SqlTools.csproj -c Release -o ./nupkg
|
|
```
|
|
|
|
### Validate Package
|
|
```powershell
|
|
dotnet tool install -g dotnet-validate
|
|
dotnet validate package nupkg/Strata.SqlTools.1.0.0.nupkg
|
|
```
|
|
|
|
### Publish to NuGet.org
|
|
```powershell
|
|
dotnet nuget push nupkg/Strata.SqlTools.1.0.0.nupkg --api-key YOUR_API_KEY --source https://api.nuget.org/v3/index.json
|
|
```
|
|
|
|
## 📚 Additional Resources
|
|
|
|
- [NuGet Package Best Practices](https://learn.microsoft.com/en-us/nuget/create-packages/package-authoring-best-practices)
|
|
- [.NET Library Guidance](https://learn.microsoft.com/en-us/dotnet/standard/library-guidance/)
|
|
- [API Design Guidelines](https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/)
|
|
- [Source Link](https://github.com/dotnet/sourcelink)
|