universal-dev-standards 3.5.1-beta.1 → 3.5.1-beta.11

package/bundled/core/versioning.md

@@ -0,0 +1,902 @@
+# Semantic Versioning Standard
+
+> **Language**: English | [繁體中文](../locales/zh-TW/core/versioning.md)
+
+**Version**: 1.2.0
+**Last Updated**: 2025-12-30
+**Applicability**: All software projects with versioned releases
+
+---
+
+## Purpose
+
+This standard defines how to version software releases using Semantic Versioning (SemVer) to communicate changes clearly to users and maintainers.
+
+---
+
+## Semantic Versioning Format
+
+```
+MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]
+
+Examples:
+2.3.1
+1.0.0-alpha.1
+3.2.0-beta.2+20250112
+```
+
+### Components
+
+| Component | Purpose | When to Increment |
+|-----------|---------|-------------------|
+| **MAJOR** | Breaking changes | Incompatible API changes |
+| **MINOR** | New features | Backward-compatible functionality |
+| **PATCH** | Bug fixes | Backward-compatible bug fixes |
+| **PRERELEASE** | Pre-release identifier | Alpha, beta, rc versions |
+| **BUILD** | Build metadata | Build number, commit hash |
+
+---
+
+## Incrementing Rules
+
+### MAJOR Version (X.0.0)
+
+**Increment when**:
+- Breaking API changes
+- Removing deprecated features
+- Major architecture changes
+- Incompatible behavior changes
+
+**Examples**:
+```
+1.9.5 → 2.0.0  # Remove deprecated API
+3.2.1 → 4.0.0  # Change return type of public method
+```
+
+**Guidelines**:
+- Reset MINOR and PATCH to 0
+- Document migration guide
+- Provide deprecation warnings in previous MINOR versions
+
+---
+
+### MINOR Version (x.Y.0)
+
+**Increment when**:
+- Adding new features (backward-compatible)
+- Deprecating features (not removing)
+- Substantial internal improvements
+- New public APIs
+
+**Examples**:
+```
+2.3.5 → 2.4.0  # Add new API endpoint
+1.12.0 → 1.13.0  # Add optional parameter to existing function
+```
+
+**Guidelines**:
+- Reset PATCH to 0
+- Existing functionality unchanged
+- New features are opt-in
+
+---
+
+### PATCH Version (x.y.Z)
+
+**Increment when**:
+- Bug fixes (no new features)
+- Security patches
+- Documentation corrections
+- Internal refactoring (no API changes)
+
+**Examples**:
+```
+3.1.2 → 3.1.3  # Fix null pointer exception
+2.0.0 → 2.0.1  # Security vulnerability patch
+```
+
+**Guidelines**:
+- No new functionality
+- No API changes
+- Safe to update immediately
+
+---
+
+## Pre-release Versions
+
+Format: `MAJOR.MINOR.PATCH-PRERELEASE`
+
+### Pre-release Identifiers
+
+| Identifier | Purpose | Stability | Audience |
+|------------|---------|-----------|----------|
+| `alpha` | Early testing | Unstable | Internal team |
+| `beta` | Feature complete | Mostly stable | Early adopters |
+| `rc` (release candidate) | Final testing | Stable | Beta testers |
+
+### Examples
+
+```
+1.0.0-alpha.1       # First alpha release
+1.0.0-alpha.2       # Second alpha release
+1.0.0-beta.1        # First beta release
+1.0.0-beta.2        # Second beta release
+1.0.0-rc.1          # Release candidate 1
+1.0.0               # Stable release
+```
+
+### Ordering
+
+Pre-releases are ordered lexicographically:
+```
+1.0.0-alpha.1 < 1.0.0-alpha.2 < 1.0.0-beta.1 < 1.0.0-rc.1 < 1.0.0
+```
+
+---
+
+## Build Metadata
+
+Format: `MAJOR.MINOR.PATCH+BUILD`
+
+### Examples
+
+```
+1.0.0+20250112            # Date-based build
+2.3.1+001                 # Sequential build number
+3.0.0+sha.5114f85         # Git commit hash
+1.2.0-beta.1+exp.sha.5114f85  # Combined pre-release and build
+```
+
+### Guidelines
+
+- Build metadata SHOULD NOT affect version precedence
+- Use for CI/CD tracking
+- Include in artifacts but not in version comparison
+
+---
+
+## Initial Development
+
+### Version 0.x.x
+
+```
+0.1.0  # Initial development release
+0.2.0  # Add features
+0.3.0  # Add more features
+...
+1.0.0  # First stable release
+```
+
+**Guidelines**:
+- Major version 0 indicates development phase
+- API may change frequently
+- Breaking changes allowed in MINOR versions
+- Move to 1.0.0 when API is stable
+
+---
+
+## Version Lifecycle
+
+### Example Release Cycle
+
+```
+Development Phase:
+0.1.0 → 0.2.0 → 0.9.0
+
+First Stable Release:
+1.0.0
+
+Feature Additions:
+1.0.0 → 1.1.0 → 1.2.0
+
+Bug Fixes:
+1.2.0 → 1.2.1 → 1.2.2
+
+Next Major Release:
+1.2.2 → 2.0.0-alpha.1 → 2.0.0-beta.1 → 2.0.0-rc.1 → 2.0.0
+```
+
+---
+
+## Changelog Integration
+
+> **See Also**: For comprehensive CHANGELOG writing guidelines, see [changelog-standards.md](changelog-standards.md).
+
+### CHANGELOG.md Format
+
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+- New feature X
+- New API endpoint Y
+
+### Changed
+- Updated dependency Z to v3.0
+
+### Deprecated
+- Method A will be removed in v3.0
+
+### Removed
+- Old API endpoint B
+
+### Fixed
+- Bug fix for issue #123
+
+### Security
+- Security vulnerability patch
+
+## [2.1.0] - 2025-11-12
+
+### Added
+- OAuth2 authentication support
+- Email notification system
+
+### Fixed
+- Memory leak in user session cache
+
+## [2.0.0] - 2025-10-01
+
+### Changed
+- **BREAKING**: User API response format
+
+### Removed
+- **BREAKING**: Deprecated v1 endpoints
+
+## [1.5.2] - 2025-09-15
+
+### Fixed
+- Null pointer exception in payment module
+
+[Unreleased]: https://github.com/user/repo/compare/v2.1.0...HEAD
+[2.1.0]: https://github.com/user/repo/compare/v2.0.0...v2.1.0
+[2.0.0]: https://github.com/user/repo/compare/v1.5.2...v2.0.0
+[1.5.2]: https://github.com/user/repo/releases/tag/v1.5.2
+```
+
+### Exclusion Rules
+
+CHANGELOG should NOT record the following types of changes:
+
+#### 1. Directories Excluded by `.gitignore`
+
+Directories excluded from version control will not be committed, so they should not be recorded in CHANGELOG.
+
+**Principle**: Any directories or files listed in the project's `.gitignore` should not be recorded in CHANGELOG.
+
+**Common Exclusion Categories (Examples)**:
+
+| Category | Common Directories/Files | Reason |
+|----------|-------------------------|--------|
+| AI Collaboration Tools | `.claude/`, `.cursor/`, `.ai/` | Local development aids, not in version control |
+| Development Standards | `.standards/`, `docs/internal/` | Local standard docs, not in version control |
+| Build Outputs | `dist/`, `build/`, `out/` | Build artifacts, not in version control |
+| Large Data | `data/`, `datasets/` | Data files, not in version control |
+
+**Verification Method**:
+
+**macOS / Linux:**
+```bash
+# Before generating CHANGELOG, check project's .gitignore exclusions
+cat .gitignore | grep -E "^[^#*]" | head -20
+```
+
+**Windows PowerShell:**
+```powershell
+# Before generating CHANGELOG, check project's .gitignore exclusions
+Get-Content .gitignore | Where-Object { $_ -match "^[^#*]" } | Select-Object -First 20
+```
+
+**Note**: Each project should determine exclusions based on its own `.gitignore` settings. The table above is just a common example.
+
+#### 2. Build Artifacts and Temporary Files
+
+The following types of changes should also not be recorded:
+
+- `bin/`, `obj/`, `Release/`, `Debug/` and other build outputs
+- `*.log`, `*.tmp` and other temporary files
+- `node_modules/`, `packages/` and other dependency directories
+
+#### 3. Environment and Configuration Files (Sensitive Data)
+
+Files containing sensitive data should not be recorded:
+
+- `*.env`, `.env.*` environment variable files
+- `*.local.json`, `*.local.yaml` local configuration files (e.g., .NET's `appsettings.*.local.json`)
+- `*.pem`, `*.key`, `*.p12` key and certificate files
+- `credentials.*`, `secrets.*` credential files
+
+### Best Practice
+
+When generating CHANGELOG, follow this process:
+
+1. **List changed commits**
+
+   **macOS / Linux / Windows (Git):**
+   ```bash
+   git log main..HEAD --oneline
+   ```
+
+2. **Exclude commits that don't need recording**
+   - Commits containing "gitignore", "version control", or "misc(version control)" types
+   - Commits that only modify excluded directories
+
+3. **Categorize records**
+   - Only record actual code or documentation changes that will be committed to the repository
+   - Ensure all recorded file paths exist in the repository
+
+4. **Verify records**
+
+   **macOS / Linux:**
+   ```bash
+   # Verify that recorded paths exist in the repository
+   git ls-files | grep -E "path/to/file"
+   ```
+
+   **Windows PowerShell:**
+   ```powershell
+   # Verify that recorded paths exist in the repository
+   git ls-files | Select-String -Pattern "path/to/file"
+   ```
+
+---
+
+## Release Process
+
+### Overview
+
+The complete Release process includes 5 phases:
+
+1. **Pre-release Diagnosis** - Mandatory
+2. **Environment Preparation**
+3. **Package Generation**
+4. **Deployment Execution**
+5. **Post-release Verification**
+
+### Phase 1: Pre-release Diagnosis - Mandatory
+
+**Purpose**: Assess the target server's environment status before generating the upgrade package
+
+**Check Items**:
+- System tool versions
+- Required drivers
+- Disk space
+- Database connectivity
+- Application version
+- Configuration completeness
+
+**Pass Conditions** (Quality Gate):
+- All required tools installed
+- Sufficient disk space (at least 500MB)
+- Database connection normal
+- No system-level errors
+
+**Failure Handling**:
+- If diagnosis fails, execute Environment Preparation (Phase 2)
+- Re-execute diagnosis after fixes
+- Must not skip diagnosis and proceed directly to packaging
+
+---
+
+### Phase 2: Environment Preparation
+
+**Purpose**: Install missing tools and drivers according to diagnosis report results
+
+**Verification Standards**:
+- All diagnosis items passed
+- Database connection test successful
+- Verification tools show no errors
+
+---
+
+### Phase 3: Package Generation
+
+**Purpose**: Generate upgrade package containing the latest version
+
+**Execution Steps**:
+```bash
+# 1. Confirm current branch and version
+git branch
+git describe --tags
+
+# 2. Generate upgrade package (using project-provided packaging script)
+./tools/generate-upgrade-package.sh -v v1.2.1 -o ./dist
+
+# 3. Verify upgrade package contents
+tar -tzf dist/upgrade-package-*.tar.gz | head -20
+```
+
+#### Upgrade Package Naming
+
+**Format**: `{PROJECT}-upgrade-v{VERSION}-{DATE}.tar.gz`
+
+| Element | Description | Examples |
+|---------|-------------|----------|
+| `{PROJECT}` | Project name (replace with actual project name) | `my-app`, `api-server` |
+| `{VERSION}` | Version number (consistent with Git tag) | `1.2.1`, `2.0.0-beta.1` |
+| `{DATE}` | Packaging date (YYYYMMDD) | `20251128` |
+
+**Examples** (replace `{PROJECT}` with your project name):
+```
+{PROJECT}-upgrade-v1.2.1-20251127.tar.gz
+{PROJECT}-upgrade-v2.0.0-beta.1-20251201.tar.gz
+```
+
+---
+
+### Phase 4: Deployment Execution
+
+**Purpose**: Execute upgrade on target server
+
+**Execution Steps**:
+```bash
+# 1. Upload upgrade package to target server
+scp upgrade-package-*.tar.gz user@target:/tmp/
+
+# 2. Extract upgrade package
+cd /tmp
+tar -xzf upgrade-package-*.tar.gz
+cd upgrade-package-*/
+
+# 3. Dry-run test (strongly recommended)
+sudo ./upgrade.sh --dry-run
+
+# 4. Actual upgrade
+sudo ./upgrade.sh
+```
+
+**Deployment Verification**:
+- Backup created
+- Service stopped successfully
+- Files deployed successfully
+- Schema migration successful (if applicable)
+- Service started successfully
+
+---
+
+### Phase 5: Post-release Verification
+
+**Purpose**: Confirm upgrade success and application running normally
+
+**Check Items**:
+```bash
+# 1. Check service status
+systemctl status your-service
+
+# 2. Check application version
+curl http://localhost:PORT/api/version
+
+# 3. Check logs for no errors
+tail -100 /path/to/app.log | grep -i error
+```
+
+**Success Criteria**:
+- Service running normally
+- API returns correct version number
+- No fatal errors in logs
+- Functionality verification passed
+
+---
+
+### Release Checklist
+
+**Pre-release (Diagnosis and Preparation)**:
+- [ ] Execute server diagnosis
+- [ ] Diagnosis report passes all check items
+- [ ] Environment preparation completed (if missing)
+- [ ] Environment verification tools passed
+
+**Release (Packaging and Deployment)**:
+- [ ] Upgrade package generated successfully
+- [ ] Upgrade package contents verified
+- [ ] Dry-run test no anomalies
+- [ ] Backup plan prepared
+- [ ] Rollback plan prepared
+
+**Post-release (Verification and Monitoring)**:
+- [ ] Service started successfully
+- [ ] Version number correct
+- [ ] Functionality verification passed
+- [ ] No anomalies in logs
+
+---
+
+### Quality Gates
+
+The following checkpoints **must pass**, otherwise cannot proceed to next phase:
+
+| Phase | Gate | Failure Handling |
+|-------|------|------------------|
+| **Diagnosis** | Diagnosis report no errors | Environment preparation |
+| **Preparation** | Verification tools passed | Fix and re-verify |
+| **Packaging** | Upgrade package structure complete | Re-package |
+| **Deployment** | Dry-run no anomalies | Analyze logs and fix |
+| **Verification** | Service running normally | Rollback |
+
+---
+
+### Rollback Plan
+
+If upgrade fails, execute the following rollback steps:
+
+```bash
+# 1. Stop service
+sudo systemctl stop your-service
+
+# 2. Restore backup
+BACKUP_PATH="/path/to/backup-$(date +%Y%m%d)"
+sudo rm -rf /path/to/app
+sudo mv "$BACKUP_PATH" /path/to/app
+
+# 3. Restart service
+sudo systemctl start your-service
+
+# 4. Verify rollback success
+sudo systemctl status your-service
+```
+
+---
+
+### Compliance
+
+**Mandatory Requirements**:
+- Must not skip diagnosis phase
+- Must not skip dry-run test
+- Must retain diagnosis report
+- Must prepare rollback plan
+
+**Audit Trail**:
+- All Release documentation retained for at least 12 months
+- Diagnosis report associated with Git Tag
+- Upgrade logs preserved completely
+
+---
+
+## Version Tagging in Git
+
+### Creating Tags
+
+```bash
+# Annotated tag (recommended)
+git tag -a v1.2.0 -m "Release version 1.2.0"
+
+# Tag with detailed message
+git tag -a v2.0.0 -m "Release version 2.0.0
+
+Major changes:
+- New authentication system
+- Redesigned API
+- Performance improvements"
+
+# Push tag to remote
+git push origin v1.2.0
+
+# Push all tags
+git push origin --tags
+```
+
+### Tag Naming Convention
+
+```
+v1.0.0          ✅ Recommended (with 'v' prefix)
+1.0.0           ✅ Acceptable (without 'v')
+version-1.0.0   ❌ Avoid (too verbose)
+1.0             ❌ Avoid (incomplete version)
+```
+
+---
+
+## Automation Tools
+
+### standard-version (Node.js)
+
+```bash
+# Install
+npm install --save-dev standard-version
+
+# Add to package.json
+{
+  "scripts": {
+    "release": "standard-version"
+  }
+}
+
+# Create release
+npm run release              # Auto-increment based on commits
+npm run release -- --release-as minor  # Force minor version
+npm run release -- --release-as 2.0.0  # Specific version
+```
+
+### semantic-release (Node.js)
+
+```bash
+# Install
+npm install --save-dev semantic-release
+
+# Configure in .releaserc.json
+{
+  "branches": ["main"],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/changelog",
+    "@semantic-release/npm",
+    "@semantic-release/git",
+    "@semantic-release/github"
+  ]
+}
+```
+
+---
+
+## Dependency Version Ranges
+
+### npm (package.json)
+
+```json
+{
+  "dependencies": {
+    "exact": "1.2.3",           // Exact version
+    "patch": "~1.2.3",          // >=1.2.3 <1.3.0
+    "minor": "^1.2.3",          // >=1.2.3 <2.0.0
+    "range": ">=1.2.3 <2.0.0",  // Explicit range
+    "latest": "*"               // ❌ Avoid - any version
+  }
+}
+```
+
+**Recommendations**:
+- Use `^` for most dependencies (minor updates)
+- Use `~` for conservative updates (patch only)
+- Use exact versions for critical dependencies
+- Never use `*` in production
+
+---
+
+### .NET (csproj)
+
+```xml
+<ItemGroup>
+  <!-- Exact version -->
+  <PackageReference Include="Newtonsoft.Json" Version="13.0.1" />
+
+  <!-- Minimum version -->
+  <PackageReference Include="Microsoft.Extensions.Logging" Version="[8.0.0,)" />
+
+  <!-- Version range -->
+  <PackageReference Include="AutoMapper" Version="[12.0.0,13.0.0)" />
+</ItemGroup>
+```
+
+---
+
+## Breaking Change Communication
+
+### 1. Deprecation Warnings (N-1 Version)
+
+```javascript
+// Version 1.5.0 - Add deprecation warning
+/**
+ * @deprecated Use authenticateV2() instead. Will be removed in v2.0.0
+ */
+function authenticate(username, password) {
+  console.warn('[DEPRECATED] authenticate() will be removed in v2.0.0. Use authenticateV2()');
+  return authenticateV2(username, password);
+}
+```
+
+### 2. API Versioning Strategies
+
+Choose an API versioning strategy based on your needs:
+
+| Strategy | Format | Pros | Cons |
+|----------|--------|------|------|
+| URL Path | `/api/v1/users` | Clear, easy routing | URL pollution |
+| Query Parameter | `/api/users?version=1` | Optional versioning | Cache issues |
+| Header | `Accept: application/vnd.api.v1+json` | Clean URLs | Less visible |
+| Content Negotiation | `Accept: application/vnd.api+json;version=1` | RESTful | Complex |
+
+**Recommended**: URL Path versioning for most APIs (clearest for developers).
+
+### 3. Deprecation Timeline
+
+Follow this timeline when deprecating API features:
+
+```
+v1.0.0 - Feature introduced
+v1.5.0 - Deprecation warning added (minimum N-1 version)
+v2.0.0 - Feature removed (document in migration guide)
+```
+
+**Deprecation Period Guidelines**:
+
+| API Type | Minimum Deprecation Period |
+|----------|---------------------------|
+| Internal API | 1 minor version |
+| Partner API | 2 minor versions + 3 months |
+| Public API | 2 minor versions + 6 months |
+| Critical Infrastructure | 1 year minimum |
+
+### 4. Backward Compatibility Checklist
+
+Before releasing, verify these backward compatibility rules:
+
+**DO NOT break (without major version bump)**:
+- [ ] Remove public API endpoints
+- [ ] Remove required request fields
+- [ ] Add required request fields
+- [ ] Change response field types
+- [ ] Change error code meanings
+- [ ] Remove response fields consumers depend on
+
+**Safe changes (minor/patch version)**:
+- [ ] Add optional request fields
+- [ ] Add new response fields
+- [ ] Add new endpoints
+- [ ] Add new error codes
+- [ ] Improve error messages
+- [ ] Performance improvements
+
+### 5. Migration Guide (N Version)
+
+```markdown
+# Migration Guide: v1.x to v2.0
+
+## Breaking Changes
+
+### 1. authenticate() removed
+
+**Before (v1.x)**:
+```javascript
+const token = await authenticate('user', 'pass');
+```
+
+**After (v2.0)**:
+```javascript
+const token = await authenticateV2({ username: 'user', password: 'pass' });
+```
+
+### 2. API response format changed
+
+**Before (v1.x)**:
+```json
+{ "data": { "user": {...} } }
+```
+
+**After (v2.0)**:
+```json
+{ "user": {...} }
+```
+
+Update your code:
+```javascript
+// Before
+const user = response.data.user;
+
+// After
+const user = response.user;
+```
+```
+
+---
+
+## Project Configuration
+
+### Document in README.md
+
+```markdown
+## Versioning
+
+This project follows [Semantic Versioning 2.0.0](https://semver.org/).
+
+### Version Format
+`MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]`
+
+### Release Cycle
+- **Major releases**: Annually (breaking changes)
+- **Minor releases**: Quarterly (new features)
+- **Patch releases**: As needed (bug fixes)
+
+### Support Policy
+- Latest major version: Full support
+- Previous major version: Security fixes only (1 year)
+- Older versions: No support
+
+### Changelog
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+```
+
+---
+
+## Version Comparison
+
+### Precedence Rules
+
+```
+1.0.0 < 2.0.0 < 2.1.0 < 2.1.1
+
+1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta < 1.0.0-rc.1 < 1.0.0
+
+1.0.0 < 1.0.0+001 (build metadata ignored in precedence)
+```
+
+### Comparison in Code
+
+```javascript
+// JavaScript (using semver package)
+const semver = require('semver');
+
+semver.gt('1.2.3', '1.2.2');  // true
+semver.satisfies('1.2.3', '^1.0.0');  // true
+semver.major('2.3.1');  // 2
+```
+
+---
+
+## Common Questions
+
+### Q: When should I release 1.0.0?
+
+**A**: When your API is stable and you're ready to commit to backward compatibility.
+
+---
+
+### Q: Should I bump MAJOR for internal breaking changes?
+
+**A**: No, only for public API changes. Internal refactoring is PATCH or MINOR.
+
+---
+
+### Q: Can I skip versions?
+
+**A**: Yes, but not recommended. Use sequential versioning for clarity.
+
+---
+
+### Q: How do I version libraries vs applications?
+
+**A**:
+- **Libraries**: Strictly follow SemVer (API matters)
+- **Applications**: Can be more flexible (user experience matters)
+
+---
+
+## Related Standards
+
+- [Changelog Standards](changelog-standards.md)
+- [Git Workflow Standards](git-workflow.md)
+- [Commit Message Guide](commit-message-guide.md)
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.2.0 | 2025-12-30 | Added: API Versioning Strategies, Deprecation Timeline, Backward Compatibility Checklist |
+| 1.1.3 | 2025-12-24 | Added: Related Standards section |
+| 1.1.2 | 2025-12-11 | Improved: Upgrade package naming example to use generic placeholders instead of hardcoded project names |
+| 1.1.1 | 2025-12-04 | Refactored: CHANGELOG exclusion rules to be more generic (removed project-specific directories) |
+| 1.1.0 | 2025-12-04 | Added: CHANGELOG exclusion rules, Release Process section |
+| 1.0.0 | 2025-11-12 | Initial versioning standard |
+
+---
+
+## References
+
+- [Semantic Versioning 2.0.0](https://semver.org/)
+- [Keep a Changelog](https://keepachangelog.com/)
+- [Calendar Versioning](https://calver.org/) (alternative scheme)
+
+---
+
+## License
+
+This standard is released under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).