|
| 1 | +# Shipping Guide for Evoq.Blockchain |
| 2 | + |
| 3 | +This document outlines the complete process for shipping a new release of Evoq.Blockchain to ensure consistency and prevent version mismatches. |
| 4 | + |
| 5 | +## Pre-Release Checklist |
| 6 | + |
| 7 | +Before starting the release process, ensure: |
| 8 | + |
| 9 | +- [ ] All tests pass (`dotnet test`) |
| 10 | +- [ ] No critical warnings in build |
| 11 | +- [ ] All public APIs are documented |
| 12 | +- [ ] No TODO comments remain |
| 13 | +- [ ] Changes are committed and pushed to main branch |
| 14 | +- [ ] Working directory is clean (`git status`) |
| 15 | + |
| 16 | +## Release Process |
| 17 | + |
| 18 | +### 1. Version Management |
| 19 | + |
| 20 | +**CRITICAL**: Always check current versions before proceeding: |
| 21 | + |
| 22 | +```bash |
| 23 | +# Check current project version |
| 24 | +grep '<Version>' src/Evoq.Blockchain/Evoq.Blockchain.csproj |
| 25 | + |
| 26 | +# Check latest git tag |
| 27 | +git tag --list --sort=-version:refname | head -1 |
| 28 | + |
| 29 | +# Check latest NuGet version |
| 30 | +curl -s "https://api.nuget.org/v3/registration5-semver1/evoq.blockchain/index.json" | grep -o '"version":"[^"]*"' | tail -1 |
| 31 | +``` |
| 32 | + |
| 33 | +**Version Bump Rules**: |
| 34 | +- **PATCH** (1.6.0 → 1.6.1): Bug fixes, no new features |
| 35 | +- **MINOR** (1.6.0 → 1.7.0): New features, backward compatible |
| 36 | +- **MAJOR** (1.6.0 → 2.0.0): Breaking changes |
| 37 | + |
| 38 | +### 2. Update Version |
| 39 | + |
| 40 | +Update the version in `src/Evoq.Blockchain/Evoq.Blockchain.csproj`: |
| 41 | + |
| 42 | +```xml |
| 43 | +<Version>1.8.0</Version> |
| 44 | +``` |
| 45 | + |
| 46 | +### 3. Update CHANGELOG.md |
| 47 | + |
| 48 | +Add a new entry at the top of `CHANGELOG.md`: |
| 49 | + |
| 50 | +```markdown |
| 51 | +## [1.8.0] - 2024-01-XX |
| 52 | + |
| 53 | +### Added |
| 54 | +- Selective disclosure functionality with `MerkleTree.From()` methods |
| 55 | +- `TryReadJsonKeys()` method on `MerkleLeaf` for JSON key extraction |
| 56 | +- V3.0 metadata leaf preservation during selective disclosure |
| 57 | +- `NonJsonLeafException` for non-JSON leaf handling |
| 58 | + |
| 59 | +### Fixed |
| 60 | +- V3.0 header leaf salt preservation during selective disclosure |
| 61 | +- Root hash consistency across selective disclosure operations |
| 62 | + |
| 63 | +### Changed |
| 64 | +- Enhanced metadata leaf detection with flexible content type matching |
| 65 | +``` |
| 66 | + |
| 67 | +### 4. Build and Test |
| 68 | + |
| 69 | +```bash |
| 70 | +# Run full build and test suite |
| 71 | +./build.sh |
| 72 | + |
| 73 | +# Verify package was created |
| 74 | +ls -la artifacts/ |
| 75 | +``` |
| 76 | + |
| 77 | +### 5. Commit Version Changes |
| 78 | + |
| 79 | +```bash |
| 80 | +# Commit version and changelog updates |
| 81 | +git add . |
| 82 | +git commit -m "Bump version to 1.8.0 for selective disclosure release" |
| 83 | +git push origin master |
| 84 | +``` |
| 85 | + |
| 86 | +### 6. Create Git Tag |
| 87 | + |
| 88 | +```bash |
| 89 | +# Create annotated tag |
| 90 | +git tag -a v1.8.0 -m "Version 1.8.0 - Add selective disclosure with V3.0 metadata preservation" |
| 91 | + |
| 92 | +# Push tag to remote |
| 93 | +git push origin v1.8.0 |
| 94 | +``` |
| 95 | + |
| 96 | +### 7. Create GitHub Release |
| 97 | + |
| 98 | +**Option A: Using GitHub CLI (Recommended)** |
| 99 | +```bash |
| 100 | +# Create release with changelog from file |
| 101 | +gh release create v1.8.0 \ |
| 102 | + --title "Version 1.8.0 - Selective Disclosure with V3.0 Metadata Preservation" \ |
| 103 | + --notes-file CHANGELOG.md |
| 104 | + |
| 105 | +# Or create with inline notes |
| 106 | +gh release create v1.8.0 \ |
| 107 | + --title "Version 1.8.0 - Selective Disclosure with V3.0 Metadata Preservation" \ |
| 108 | + --notes "Added selective disclosure functionality with V3.0 metadata preservation..." |
| 109 | +``` |
| 110 | + |
| 111 | +**Option B: Using GitHub Web Interface** |
| 112 | +1. Go to https://github.com/lukepuplett/evoq-blockchain/releases |
| 113 | +2. Click "Create a new release" |
| 114 | +3. Select the tag you just pushed (v1.8.0) |
| 115 | +4. Set release title: "Version 1.8.0 - Selective Disclosure with V3.0 Metadata Preservation" |
| 116 | +5. Copy the changelog content from `CHANGELOG.md` |
| 117 | +6. **DO NOT** upload the .nupkg file manually - let the publish script handle it |
| 118 | +7. Click "Publish release" |
| 119 | + |
| 120 | +### 8. Publish to NuGet |
| 121 | + |
| 122 | +**Manual Upload to NuGet.org**: |
| 123 | +1. Go to https://www.nuget.org/packages/manage/upload |
| 124 | +2. Upload the .nupkg file from `./artifacts/Evoq.Blockchain.1.8.0.nupkg` |
| 125 | +3. Verify package metadata and click "Submit" |
| 126 | + |
| 127 | +**Alternative: Using publish script** (if automated publishing is preferred): |
| 128 | +```bash |
| 129 | +# Set your NuGet API key |
| 130 | +export NUGET_API_KEY="your-nuget-api-key" |
| 131 | + |
| 132 | +# Publish to NuGet.org |
| 133 | +./publish.sh |
| 134 | +``` |
| 135 | + |
| 136 | +### 9. Verify Release |
| 137 | + |
| 138 | +After publishing, verify: |
| 139 | + |
| 140 | +```bash |
| 141 | +# Check NuGet.org has the new version |
| 142 | +curl -s "https://api.nuget.org/v3/registration5-semver1/evoq.blockchain/index.json" | grep -o '"version":"[^"]*"' | tail -1 |
| 143 | + |
| 144 | +# Should show: "version":"1.8.0" |
| 145 | +``` |
| 146 | + |
| 147 | +## Common Issues and Solutions |
| 148 | + |
| 149 | +### Version Mismatch |
| 150 | +If you see different versions in different places: |
| 151 | +1. **Project file**: Check `src/Evoq.Blockchain/Evoq.Blockchain.csproj` |
| 152 | +2. **Git tags**: Check `git tag --list` |
| 153 | +3. **NuGet.org**: Check the API response above |
| 154 | + |
| 155 | +### Missing Git Tag |
| 156 | +If a version was published to NuGet but no git tag exists: |
| 157 | +1. Create the missing tag: `git tag -a v1.7.0 -m "Version 1.7.0 - Previous release"` |
| 158 | +2. Push the tag: `git push origin v1.7.0` |
| 159 | +3. Create a GitHub release for that tag |
| 160 | + |
| 161 | +### Build Failures |
| 162 | +If `./build.sh` fails: |
| 163 | +1. Check for test failures: `dotnet test` |
| 164 | +2. Check for build warnings: `dotnet build --configuration Release` |
| 165 | +3. Fix issues before proceeding |
| 166 | + |
| 167 | +## Release Templates |
| 168 | + |
| 169 | +### Git Tag Message Template |
| 170 | +``` |
| 171 | +Version X.Y.Z - Brief description of main features |
| 172 | +
|
| 173 | +- Feature 1 description |
| 174 | +- Feature 2 description |
| 175 | +- Fix 1 description |
| 176 | +``` |
| 177 | + |
| 178 | +### GitHub Release Title Template |
| 179 | +``` |
| 180 | +Version X.Y.Z - Main Feature Description |
| 181 | +``` |
| 182 | + |
| 183 | +### Changelog Entry Template |
| 184 | +```markdown |
| 185 | +## [X.Y.Z] - YYYY-MM-DD |
| 186 | + |
| 187 | +### Added |
| 188 | +- New feature 1 |
| 189 | +- New feature 2 |
| 190 | + |
| 191 | +### Fixed |
| 192 | +- Bug fix 1 |
| 193 | +- Bug fix 2 |
| 194 | + |
| 195 | +### Changed |
| 196 | +- Breaking change 1 |
| 197 | +- Enhancement 1 |
| 198 | +``` |
| 199 | + |
| 200 | +## Managing Releases with GitHub CLI |
| 201 | + |
| 202 | +### Useful GitHub CLI Commands |
| 203 | +```bash |
| 204 | +# List all releases |
| 205 | +gh release list |
| 206 | + |
| 207 | +# View a specific release |
| 208 | +gh release view v1.8.0 |
| 209 | + |
| 210 | +# Edit an existing release |
| 211 | +gh release edit v1.8.0 --title "New Title" --notes "New notes" |
| 212 | + |
| 213 | +# Create a draft release for review |
| 214 | +gh release create v1.8.0 --title "Version 1.8.0" --notes "Notes" --draft |
| 215 | + |
| 216 | +# Upload assets to an existing release |
| 217 | +gh release upload v1.8.0 artifacts/Evoq.Blockchain.1.8.0.nupkg |
| 218 | +``` |
| 219 | + |
| 220 | +### Authentication |
| 221 | +Make sure you're authenticated with GitHub CLI: |
| 222 | +```bash |
| 223 | +# Check authentication status |
| 224 | +gh auth status |
| 225 | + |
| 226 | +# Login if needed |
| 227 | +gh auth login |
| 228 | +``` |
| 229 | + |
| 230 | +## Emergency Procedures |
| 231 | + |
| 232 | +### Reverting a Release |
| 233 | +If a release needs to be reverted: |
| 234 | + |
| 235 | +1. **DO NOT** delete the git tag (it's immutable) |
| 236 | +2. **DO NOT** unpublish from NuGet (it's permanent) |
| 237 | +3. Create a new patch release with fixes |
| 238 | +4. Document the issue in the changelog |
| 239 | + |
| 240 | +### Hotfix Release |
| 241 | +For critical bug fixes: |
| 242 | + |
| 243 | +1. Create a hotfix branch: `git checkout -b hotfix/1.8.1` |
| 244 | +2. Make minimal changes to fix the issue |
| 245 | +3. Bump version to 1.8.1 |
| 246 | +4. Follow normal release process |
| 247 | +5. Merge hotfix branch back to master |
| 248 | + |
| 249 | +## Automation Ideas |
| 250 | + |
| 251 | +Future improvements could include: |
| 252 | +- GitHub Actions for automated releases |
| 253 | +- Automated version bumping |
| 254 | +- Automated changelog generation |
| 255 | +- Automated NuGet publishing |
| 256 | +- Release validation checks |
0 commit comments