nu_plugin_secret 0.7.0

# Release Procedures and Versioning Strategy

This document outlines the release process, versioning strategy, and procedures for `nu_plugin_secret`.

## 🏷️ Versioning Strategy

### Semantic Versioning

We follow [Semantic Versioning](https://semver.org/) (SemVer) with security-first considerations:

```
MAJOR.MINOR.PATCH
```

- **MAJOR**: Breaking changes, API changes, security architecture changes
- **MINOR**: New features, new secret types, new commands (backward compatible)
- **PATCH**: Bug fixes, security patches, dependency updates

### Version Examples

- `0.1.0` → `0.1.1`: Security patch or bug fix
- `0.1.1` → `0.2.0`: New secret type or command added
- `0.2.0` → `1.0.0`: API stabilization, breaking changes, or major security overhaul

### Pre-release Versions

- **Alpha** (`0.1.0-alpha.1`): Early development, API may change
- **Beta** (`0.1.0-beta.1`): Feature complete, API stabilizing, testing phase
- **RC** (`0.1.0-rc.1`): Release candidate, final testing before stable

## 🚀 Release Types

### 1. Security Releases (Immediate)

**Trigger**: Security vulnerability discovered
**Timeline**: 24-48 hours
**Process**: Expedited release with minimal changes

```bash
# Security patch release
git checkout main
git pull origin main

# Apply security fix
git commit -m "security: fix vulnerability RUSTSEC-YYYY-XXXX"

# Tag and release
scripts/release.sh patch --security
```

### 2. Patch Releases (Weekly)

**Trigger**: Bug fixes, dependency updates
**Timeline**: Weekly if changes accumulated
**Process**: Standard patch process

### 3. Minor Releases (Monthly)

**Trigger**: New features, new secret types
**Timeline**: Monthly or when feature set is complete
**Process**: Full feature release

### 4. Major Releases (Quarterly+)

**Trigger**: Breaking changes, API overhaul
**Timeline**: When architectural changes needed
**Process**: Extended testing and migration support

## 📋 Release Checklist

### Pre-Release (1 week before)

- [ ] **Code Freeze**: No new features, bug fixes only
- [ ] **Security Audit**: Run comprehensive security checks
- [ ] **Dependency Update**: Update all dependencies
- [ ] **Version Bump**: Update version in Cargo.toml
- [ ] **Changelog Update**: Update CHANGELOG.md with all changes
- [ ] **Documentation Review**: Ensure all docs are current
- [ ] **Migration Guide**: Update if breaking changes

### Release Day

#### 1. Final Verification

```bash
# Run comprehensive quality checks
./scripts/check.sh

# Verify all tests pass
cargo test --all-features

# Check security audit
cargo audit

# Verify documentation builds
cargo doc --all-features

# Test plugin installation
cargo install --path .
nu -c "plugin add ~/.cargo/bin/nu_plugin_secret"
nu -c "plugin use secret; secret info"
```

#### 2. Version and Tag

```bash
# Update version in Cargo.toml
sed -i 's/version = "0.1.0"/version = "0.2.0"/' Cargo.toml

# Update Cargo.lock
cargo check

# Commit version bump
git add Cargo.toml Cargo.lock CHANGELOG.md
git commit -m "chore: bump version to 0.2.0"

# Create annotated tag
git tag -a v0.2.0 -m "Release v0.2.0

- Add SecretFloat, SecretBinary, SecretDate types
- Implement comprehensive CI/CD pipeline
- Add security testing with Miri
- Complete documentation and migration guides

🤖 Generated with Claude Code
"

# Push changes and tag
git push origin main
git push origin v0.2.0
```

#### 3. GitHub Release

```bash
# Create GitHub release using gh CLI
gh release create v0.2.0 \
  --title "nu_plugin_secret v0.2.0" \
  --notes-file release-notes.md \
  --latest

# Upload release artifacts (generated by CI)
gh release upload v0.2.0 \
  target/release-artifacts/nu_plugin_secret-linux-x86_64.tar.gz \
  target/release-artifacts/nu_plugin_secret-macos-x86_64.tar.gz \
  target/release-artifacts/nu_plugin_secret-windows-x86_64.zip
```

#### 4. Crates.io Publication

```bash
# Publish to crates.io
cargo login
cargo publish --dry-run  # Verify package
cargo publish
```

### Post-Release

- [ ] **Verify Publication**: Check crates.io listing
- [ ] **Test Installation**: `cargo install nu_plugin_secret`
- [ ] **Update Documentation**: Update docs with new version
- [ ] **Announce Release**: Social media, Discord, etc.
- [ ] **Monitor Issues**: Watch for bug reports
- [ ] **Backlog Review**: Plan next release

## 🔄 Branch Strategy

### Permanent Branches

- **`main`**: Production-ready code, always deployable
- **`develop`**: Integration branch for next release

### Temporary Branches

- **`feature/*`**: Individual features (`feature/secret-datetime`)
- **`hotfix/*`**: Critical fixes (`hotfix/security-vulnerability`)
- **`release/*`**: Release preparation (`release/0.2.0`)

### Workflow

```bash
# Feature development
git checkout develop
git checkout -b feature/secret-datetime
# ... develop feature ...
git push origin feature/secret-datetime
# ... create PR to develop ...

# Release preparation
git checkout develop
git checkout -b release/0.2.0
# ... final testing, version bump ...
git push origin release/0.2.0
# ... create PR to main ...

# Hotfix
git checkout main
git checkout -b hotfix/security-fix
# ... apply fix ...
git push origin hotfix/security-fix
# ... create PR to main AND develop ...
```

## 📝 Changelog Format

We maintain a detailed `CHANGELOG.md` following [Keep a Changelog](https://keepachangelog.com/) 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/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- New features added since last release

### Changed
- Changes to existing functionality

### Deprecated
- Soon-to-be removed features

### Removed
- Features removed in this release

### Fixed
- Bug fixes

### Security
- Security-related changes

## [0.2.0] - 2025-01-20

### Added
- SecretFloat type with NaN and infinity handling
- SecretBinary type for binary data
- SecretDate type with chrono integration
- Comprehensive CI/CD pipeline with multi-platform builds
- Memory safety testing with Miri
- Code coverage tracking with codecov.io

### Changed
- Updated MSRV to Rust 1.88.0 for nushell compatibility

### Fixed
- Plugin registration issues in CI environment
- Memory cleanup in all secret types

### Security
- Added constant-time comparison for all types
- Enhanced memory zeroization on drop
```

## 🔍 Quality Gates

### Automated Checks (Required)

All releases must pass:

- [ ] **Build**: `cargo build --all-features`
- [ ] **Tests**: `cargo test --all-features` (74+ tests)
- [ ] **Formatting**: `cargo fmt --all -- --check`
- [ ] **Linting**: `cargo clippy --all-targets --all-features -- -D warnings`
- [ ] **Documentation**: `cargo doc --no-deps --all-features`
- [ ] **Security Audit**: `cargo audit`
- [ ] **License Check**: `cargo deny check`
- [ ] **Memory Safety**: `cargo miri test`
- [ ] **Integration**: Nushell plugin registration and basic functionality

### Manual Verification

- [ ] **Installation Testing**: Test `cargo install` process
- [ ] **Cross-Platform**: Verify on Linux, macOS, Windows
- [ ] **Performance**: No significant regressions
- [ ] **Documentation**: All examples work correctly
- [ ] **Security**: No information leakage in any scenario

## 🎯 Release Targets

### v0.1.x (Current)
- **Focus**: Core functionality and stability
- **Features**: 8 secret types, 12 commands, 74 tests
- **Status**: Feature complete, security auditing

### v0.2.x (Next)
- **Focus**: Advanced features and usability
- **Planned**: 
  - `secret select` command for record field access
  - `secret get` command for list element access
  - Performance optimizations
  - Additional security enhancements

### v1.0.x (Stable)
- **Focus**: API stability and production readiness
- **Requirements**:
  - Professional security audit completed
  - 95%+ test coverage achieved
  - Community adoption demonstrated
  - API considered stable

## 📈 Success Metrics

### Release Health Indicators

- **Installation Success Rate**: >95% successful installations
- **CI/CD Pipeline**: >99% success rate
- **Test Coverage**: >95% line coverage
- **Security Audit**: Zero high/critical findings
- **Community Adoption**: Downloads, GitHub stars, usage reports

### Monitoring

- **Error Rates**: Monitor installation and usage errors
- **Performance**: Track plugin startup time and memory usage  
- **Security**: Monitor for vulnerability reports
- **Compatibility**: Track Nushell version compatibility

## 🚨 Emergency Procedures

### Security Vulnerability Response

1. **Immediate Assessment** (0-4 hours)
   - Confirm vulnerability
   - Assess severity and impact
   - Determine affected versions

2. **Fix Development** (4-24 hours)
   - Develop minimal fix
   - Test fix thoroughly
   - Prepare security advisory

3. **Emergency Release** (24-48 hours)
   - Apply version bump (patch)
   - Create security tag
   - Publish emergency release
   - Publish security advisory

4. **Communication** (Concurrent)
   - Notify maintainers
   - Prepare public disclosure
   - Update security documentation

### Critical Bug Response

Similar to security response but with slightly extended timeline (48-72 hours for non-security critical issues).

## 📞 Release Team

### Roles and Responsibilities

- **Release Manager**: Coordinates release process
- **Security Lead**: Reviews security implications
- **QA Lead**: Oversees testing and verification
- **Documentation Lead**: Ensures documentation accuracy

### Contact Information

- **Primary**: GitHub issues and discussions
- **Security**: GitHub Security Advisories
- **Emergency**: `security@nushell-works.org`

---

This release process ensures that every version of `nu_plugin_secret` meets our high standards for security, quality, and usability while maintaining predictable and transparent release cycles.