Skip to content

docs: add CHANGELOG.md and release documentation guidelines #362

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
coderdan wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: add CHANGELOG.md and release documentation guidelines #362

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
243 changes: 243 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,243 @@
# Changelog

All notable changes to CipherStash Proxy will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

## [Unreleased]

## [2.1.20] - 2026-01-29

### Added

- **Slow statement logging**: Enable with `CS_LOG__SLOW_STATEMENTS=true` to log detailed timing breakdowns when queries exceed a configurable threshold (default 2 seconds). Includes breakdown of parse, encrypt, server wait, and decrypt phases.
- **Prometheus slow statement counter**: New `cipherstash_proxy_slow_statements_total` metric increments when slow statements are detected.
- **Prometheus histogram labels**: Duration histograms now include `statement_type`, `protocol`, `mapped`, and `multi_statement` labels for granular performance analysis.
- **Term filters for STE-VEC indexes**: Support for `term_filters` configuration in `eql_v2.add_search_config()`, enabling case-insensitive JSONB queries with the `downcase` filter.

### Changed

- Updated `cipherstash-client` to v0.32.2.
- GitHub Actions jobs now timeout after 30 minutes.
- ARM64 builds migrated to Blacksmith runners.

## [2.1.9] - 2026-01-10

### Added

- Encryption sanity checks for improved error detection.
- Developer documentation updates.

### Changed

- Updated `cipherstash-client` to v0.31.1.

## [2.1.8] - 2025-12-15

### Changed

- Refactored EQL encryption logic.
- JSONB containment operator transformation improvements.
- Testing across multiple PostgreSQL versions.

## [2.1.7] - 2025-11-27

### Added

- Security documentation.

### Changed

- Improved ZeroKMS error handling.
- Database connection CLI arguments now optional.

## [2.1.6] - 2025-09-05

### Fixed

- Accurate cipher cache sizing.
- JSONB encrypted type protocol fixes.

### Changed

- Module restructuring.

## [2.1.5] - 2025-08-21

### Added

- `SET` command for `keyset_id` configuration.
- Configurable cipher caching using async Moka.

## [2.1.4] - 2025-08-08

### Changed

- Updated EQL to v2.1.8.

## [2.1.3] - 2025-08-01

### Added

- Helm chart support.
- JSONB operator integration tests.
- Comprehensive proxy/EQL showcase crate.

## [2.1.2] - 2025-07-16

### Fixed

- Common Table Expression (CTE) table resolution in EQL mapper.

## [2.1.1] - 2025-07-15

### Added

- JSON indexing for EQL v2.
- Prometheus metrics collection.
- Multiple integration test frameworks.

## [2.0.10] - 2025-06-26

### Added

- `SET` command to disable mapping.

## [2.0.9] - 2025-06-20

### Changed

- Upgraded container base image to Ubuntu 25.10.
- Updated sqltk dependency to v0.10.0.

## [2.0.8] - 2025-06-18

### Added

- Version string sent to ZeroKMS/CTS requests.

### Fixed

- Type-related issues in sqlparser.

### Changed

- Release workflow now triggers on release events.

## [2.0.7] - 2025-06-12

### Added

- Language-specific tests in integration suite.
- PostgreSQL custom and domain type identifier handling.

### Fixed

- Docker image build processes in GitHub Actions.

## [2.0.6] - 2025-06-09

### Added

- TLS and Docker configuration documentation.
- Expanded test coverage for order and group operations.

### Changed

- URL encoding for usernames in Docker entrypoint.
- Preference for CRN over workspace_id and region.

### Removed

- Order and group transformers.

## [2.0.5] - 2025-05-27

### Fixed

- Cache usage in release artifact building.

## [2.0.4] - 2025-05-26

### Added

- OIDC support.

### Fixed

- Special character handling in database configuration.
- "Insufficient data left in message" errors with null values.

## [2.0.3] - 2025-05-26

### Fixed

- Tests now ignore `CS_` environment variables during configuration validation.

### Changed

- Added environment debugging to AWS Marketplace release workflow.

## [2.0.2] - 2025-05-22

### Added

- Multi-platform Docker image builds.

### Changed

- Updated EQL to v2.0.1.

## [2.0.1] - 2025-05-21

### Added

- Encryption configuration validation.
- pgbench performance testing integration.
- ZeroKMS and CTS host configuration options.
- `GROUP BY` SQL transformations.
- EQL v2 decryption support.
- Enhanced column configuration verification.

### Fixed

- Connection termination messaging.

### Changed

- Upgraded to Rust 1.86.0 compatibility.
- Upgraded sqltk to v0.8.0.

## [2.0.0] - 2025-03-27

### Added

- Initial release of CipherStash Proxy.
- Transparent proxy for PostgreSQL with automatic encryption/decryption.
- Support for queries over encrypted values (equality, comparison, ordering).
- Docker container deployment.
- Integration with CipherStash ZeroKMS.
- Encrypt Query Language (EQL) for indexing and searching encrypted data.

[Unreleased]: https://github.com/cipherstash/proxy/compare/v2.1.20...HEAD
[2.1.20]: https://github.com/cipherstash/proxy/releases/tag/v2.1.20
[2.1.9]: https://github.com/cipherstash/proxy/releases/tag/v2.1.9
[2.1.8]: https://github.com/cipherstash/proxy/releases/tag/v2.1.8
[2.1.7]: https://github.com/cipherstash/proxy/releases/tag/v2.1.7
[2.1.6]: https://github.com/cipherstash/proxy/releases/tag/v2.1.6
[2.1.5]: https://github.com/cipherstash/proxy/releases/tag/v2.1.5
[2.1.4]: https://github.com/cipherstash/proxy/releases/tag/v2.1.4
[2.1.3]: https://github.com/cipherstash/proxy/releases/tag/v2.1.3
[2.1.2]: https://github.com/cipherstash/proxy/releases/tag/v2.1.2
[2.1.1]: https://github.com/cipherstash/proxy/releases/tag/v2.1.1
[2.0.10]: https://github.com/cipherstash/proxy/releases/tag/v2.0.10
[2.0.9]: https://github.com/cipherstash/proxy/releases/tag/v2.0.9
[2.0.8]: https://github.com/cipherstash/proxy/releases/tag/v2.0.8
[2.0.7]: https://github.com/cipherstash/proxy/releases/tag/v2.0.7
[2.0.6]: https://github.com/cipherstash/proxy/releases/tag/v2.0.6
[2.0.5]: https://github.com/cipherstash/proxy/releases/tag/v2.0.5
[2.0.4]: https://github.com/cipherstash/proxy/releases/tag/v2.0.4
[2.0.3]: https://github.com/cipherstash/proxy/releases/tag/v2.0.3
[2.0.2]: https://github.com/cipherstash/proxy/releases/tag/v2.0.2
[2.0.1]: https://github.com/cipherstash/proxy/releases/tag/v2.0.1
[2.0.0]: https://github.com/cipherstash/proxy/releases/tag/v2.0.0
51 changes: 50 additions & 1 deletion CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -178,4 +178,53 @@ mise run build:binary --target aarch64-unknown-linux-gnu
mise run build:docker --platform linux/arm64
```

The build system supports cross-compilation from macOS to Linux using MaterializeInc/crosstools.
The build system supports cross-compilation from macOS to Linux using MaterializeInc/crosstools.

## Release Documentation

### Changelog

The project maintains a `CHANGELOG.md` following [Keep a Changelog](https://keepachangelog.com/) format. When making changes that are user-facing or notable, update the changelog:

1. Add entries under an `## [Unreleased]` section at the top
2. Use appropriate subsections: `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`
3. Write entries from the user's perspective, not implementation details
4. When a release is cut, rename `[Unreleased]` to the version number and date

Example entry:
```markdown
## [Unreleased]

### Added

- **Feature name**: Brief description of what users can now do.

### Fixed

- Description of bug that was fixed.
```

### Release Announcements

For significant releases, write an `ANNOUNCEMENT.md` for the GitHub Discussions page:

1. **Title**: `CipherStash Proxy X.Y.Z Released - Brief Feature Summary`
2. **Structure**:
- Opening paragraph summarizing the release
- H2 sections for each major feature with examples
- Configuration tables where applicable
- Code examples (SQL, JSON, PromQL as relevant)
- "Other Changes" section for minor updates
- "Upgrade" section linking to the releases page
3. **Callouts**: Use GitHub callout syntax for important notes:
```markdown
> [!NOTE]
> Helpful context or clarification.

> [!TIP]
> Recommended best practices.

> [!IMPORTANT]
> Critical information users must know.
```
4. After copying content to GitHub Discussions, delete `ANNOUNCEMENT.md` from the repo