127 lines
3.0 KiB
Markdown
127 lines
3.0 KiB
Markdown
# Changelog Fragments
|
|
|
|
This directory contains changelog fragments that will be compiled into the main `CHANGELOG.md` at release time using [towncrier](https://towncrier.readthedocs.io/).
|
|
|
|
## For Contributors: Adding a Changelog Entry
|
|
|
|
When you make a change that should be documented in the changelog, create a new file in this directory.
|
|
|
|
### Creating a Fragment
|
|
|
|
Create a file in this directory with this naming pattern:
|
|
|
|
```
|
|
changelog/<PR_number>.<type>.md
|
|
```
|
|
|
|
Choose the appropriate type:
|
|
|
|
- `added.md` - New features
|
|
- `changed.md` - Changes in existing functionality
|
|
- `deprecated.md` - Soon-to-be removed features
|
|
- `removed.md` - Removed features
|
|
- `fixed.md` - Bug fixes
|
|
- `security.md` - Security fixes
|
|
|
|
Write your changelog entry as a Markdown bullet point. Include the `-` at the start:
|
|
|
|
**Example files:**
|
|
|
|
`changelog/1234.added.md`:
|
|
|
|
```markdown
|
|
- Added support for Anthropic Claude 3.5 Sonnet with improved streaming performance.
|
|
```
|
|
|
|
`changelog/5678.fixed.md`:
|
|
|
|
```markdown
|
|
- Fixed an issue where audio frames were dropped during high-load scenarios.
|
|
```
|
|
|
|
**For entries with nested bullets:**
|
|
|
|
`changelog/1234.changed.md`:
|
|
|
|
```markdown
|
|
- Updated service configuration:
|
|
|
|
- Changed default timeout to 30 seconds
|
|
- Added retry logic for failed connections
|
|
- Improved error messages
|
|
```
|
|
|
|
### Multiple Changes in One PR
|
|
|
|
**Different types of changes:** Create separate fragment files for each type:
|
|
|
|
```
|
|
changelog/1234.added.md
|
|
changelog/1234.fixed.md
|
|
```
|
|
|
|
**Multiple changes of the same type:** Create numbered fragment files:
|
|
|
|
```
|
|
changelog/1234.changed.md
|
|
changelog/1234.changed.2.md
|
|
changelog/1234.changed.3.md
|
|
```
|
|
|
|
**Related changes:** Use nested bullets in a single fragment:
|
|
|
|
```markdown
|
|
- Updated service configuration:
|
|
|
|
- Changed default timeout to 30 seconds
|
|
- Added retry logic for failed connections
|
|
```
|
|
|
|
**Rule of thumb:** One logical change per fragment file. If changes are unrelated, use separate files.
|
|
|
|
### Preview Your Changes
|
|
|
|
To see what your changelog entry will look like:
|
|
|
|
```bash
|
|
towncrier build --draft --version Unreleased
|
|
```
|
|
|
|
This won't modify any files, just show you a preview.
|
|
|
|
### When to Skip Changelog Entries
|
|
|
|
You can skip adding a changelog entry for:
|
|
|
|
- Documentation-only changes
|
|
- Internal refactoring with no user-facing impact
|
|
- Test-only changes
|
|
- CI/build configuration changes
|
|
|
|
If you're unsure whether your change needs a changelog entry, ask in your PR!
|
|
|
|
---
|
|
|
|
## For Maintainers: Releasing
|
|
|
|
### Automated Release
|
|
|
|
The changelog is automatically generated via GitHub Actions. When you're ready to release:
|
|
|
|
1. **Trigger the workflow** from GitHub Actions:
|
|
|
|
- Go to Actions → "Generate Changelog for Release"
|
|
- Click "Run workflow"
|
|
- Enter the version (e.g., `0.0.97`)
|
|
- Enter the release date (e.g., `2025-12-04`)
|
|
|
|
2. **Review the PR** that gets created automatically
|
|
|
|
3. **Merge the PR** to update the changelog
|
|
|
|
## References
|
|
|
|
- [Towncrier Documentation](https://towncrier.readthedocs.io/)
|
|
- [Keep a Changelog](https://keepachangelog.com/)
|
|
- [Contributing Guide](../CONTRIBUTING.md)
|