​

CLAUDE.md - StreamNative Release Notes Documentation

​

Purpose

​

Directory Structure

• cloud/: StreamNative Cloud release notes
• pulsar/: Apache Pulsar release notes (StreamNative distributions)
• Additional product-specific directories as needed

​

Source Code Repository Mappings

​

All Repositories Contribute

• cloud-admin: UI changes and new console features
• cloud-api-server: API additions, changes, deprecations
• cloud-manager: Platform features and billing updates
• cloud-cli: CLI command additions and changes
• sn-operator: Operator features and CRD updates
• pulsar-resources-operator: Resource management improvements
• ksn: Kafka protocol compatibility updates
• pulsar-io-bigquery: BigQuery connector updates
• pulsar-io-snowflake-streaming: Snowflake connector updates
• terraform-provider-pulsar: Pulsar provider changes
• terraform-provider-streamnative: StreamNative provider changes
• unified-rbac: Security and access control updates
• unilink: Universal linking features
• ursa-storage: Storage engine improvements

​

SNIP Repository

• snip (source_code_refs/snip/proposals/): Design proposals
  • Major features are documented in SNIP proposals
  • Reference SNIPs in release notes for context
  • Link to proposals for technical details

​

Documentation Patterns

​

Release Note Structure

1. Release Overview
   • Version number and release date
   • Major themes or focus areas
   • Compatibility notes
2. New Features
   • Headline features with descriptions
   • Benefits and use cases
   • Getting started links
3. Improvements
   • Performance enhancements
   • Usability improvements
   • API enhancements
4. Bug Fixes
   • Critical fixes
   • Security patches
   • Stability improvements
5. Breaking Changes
   • API changes
   • Configuration changes
   • Deprecations and removals
6. Known Issues
   • Limitations
   • Workarounds
   • Planned fixes
7. Upgrade Notes
   • Prerequisites
   • Upgrade procedures
   • Rollback guidance

​

Common Tasks

​

Creating Release Notes

1. Gather Changes:
   • Review git commits across repositories
   • Check merged pull requests
   • Reference SNIP proposals
   • Consult product managers
2. Categorize Updates:
   • Group by impact (features, improvements, fixes)
   • Identify breaking changes
   • Highlight security updates
3. Write Descriptions:
   • User-focused benefits
   • Clear, concise language
   • Include examples where helpful
   • Link to detailed documentation
4. Version Management:
   • Follow semantic versioning
   • Maintain version history
   • Document upgrade paths

​

Formatting Guidelines

​

Feature Entries

### Feature Name
Brief description of what the feature does and why it matters.

**Benefits:**
- Benefit 1
- Benefit 2

**Learn more:** [Feature documentation](link)

​

Breaking Changes

### Breaking Change Title
**Impact:** Who is affected and how
**Migration:** Steps to adapt to the change
**Deadline:** When old behavior will be removed (if applicable)

​

Bug Fixes

- Fixed issue where [description] (#issue-number)
- Resolved problem with [component] that caused [symptom]

​

Version Schemes

​

StreamNative Cloud

• Date-based versions (YYYY.MM.DD)
• Continuous delivery model
• Feature flags for gradual rollout

​

Operators and Tools

• Semantic versioning (X.Y.Z)
• Major.Minor.Patch scheme
• Backward compatibility guarantees

​

Connectors

• Aligned with Pulsar versions
• Compatibility matrix maintained
• Independent patch releases

​

Cross-Component Coordination

​

Cloud Releases

• Console UI (cloud-admin)
• API changes (cloud-api-server)
• New CLI commands (cloud-cli)
• RBAC updates (unified-rbac)
• Storage features (ursa-storage)

​

Private Cloud Releases

• Operator changes (sn-operator)
• Resource management (pulsar-resources-operator)
• Terraform providers
• Helm chart updates

​

Feature Dependencies

• Document cross-component requirements
• Specify minimum versions
• Note compatibility constraints
• Include upgrade order

​

Important Considerations

​

Security Updates

• Clearly mark security fixes
• Include CVE numbers
• Provide immediate action items
• Link to security advisories

​

Performance Impacts

• Quantify improvements
• Note potential regressions
• Include benchmark results
• Suggest tuning changes

​

Migration Support

• Provide migration guides
• Include rollback procedures
• Document data format changes
• Offer migration tools

​

Regional Rollouts

• Note phased deployments
• Document region availability
• Include timeline estimates
• Provide feature flag info

​

Cross-References

• Link to detailed feature docs
• Reference upgrade guides
• Point to API documentation
• Include troubleshooting resources

​

Best Practices

1. Be User-Centric: Focus on impact, not implementation
2. Be Complete: Include all significant changes
3. Be Clear: Avoid jargon and technical details
4. Be Actionable: Tell users what to do
5. Be Honest: Include known issues and limitations