chore: initial git load of code space

2026-05-12 08:52:33 -05:00
parent 9abada692f
commit 5e467bcc9c
384 changed files with 65960 additions and 2 deletions
@@ -0,0 +1,133 @@
+# 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)