Skip to content

Changelog Reference

This document provides information about the Zaojun changelog, including how to read it, versioning scheme, and how changes are documented.

Changelog Location

The official Zaojun changelog is available at: - CHANGELOG.md in the repository - Included in each release on PyPI - Displayed with zaojun --version (shows current version)

Versioning Scheme

Zaojun uses Semantic Versioning (SemVer) with the format:

MAJOR.MINOR.PATCH

Where: - MAJOR: Incremented for incompatible API changes - MINOR: Incremented for backwards-compatible functionality additions - PATCH: Incremented for backwards-compatible bug fixes

Examples:

  • 1.0.0: Initial stable release
  • 1.1.0: Added new features in a backwards-compatible manner
  • 2.0.0: Made breaking changes to the API

Why SemVer?

  • Clear communication about the nature of changes
  • Helps users understand compatibility implications
  • Standardized across the Python ecosystem
  • Facilitates dependency management

Changelog Format

The changelog is a simple chronological list of commits for each release:

Structure

# Changelog

## [Unreleased]
- Changes not yet released

## [Version] — YYYY-MM-DD
- Commit message with git hash reference [abc1234]
- Another commit message [def5678]

Entry Format

Each changelog entry includes: - Version number - Release date in YYYY-MM-DD format - List of commit messages with their git hash references

Example: 

## `0.9.8` — [2026-02-14]
- Update dependencies versions. [c34d869]

## `0.9.7` — [2026-01-24]
- Update dependencies versions. [bf6b4c1]

Reading the Changelog

For Users

  1. Check current version: zaojun --version
  2. Review recent changes: Look at the latest entries
  3. See what changed: Read commit messages to understand updates
  4. Find specific changes: Use git hash references to locate commits

For Developers

  1. Track changes: Read commit messages to understand modifications
  2. Link to code: Use git hash references to view specific commits
  3. Understand context: Commit messages provide context for changes
  4. Review history: See chronological progression of the project

Simple Commit-Based Format

The Zaojun changelog uses a straightforward commit-based format where each release entry contains:

  1. Version number with date
  2. List of commit messages from that release
  3. Git commit hash references in brackets

This format provides: - Direct link to the actual code changes - Clear chronological progression - Easy tracking of specific changes - Minimal maintenance overhead

Benefits of This Approach

  • Transparency: Each change is directly linked to its commit
  • Simplicity: No need to categorize or rewrite commit messages
  • Accuracy: Commit messages remain unchanged and authentic
  • Efficiency: Automated generation is straightforward

Dependency Updates

Dependency updates are tracked separately:

Security Updates

  • Marked with vulnerability references (e.g., GHSA-xxxx-xxxx)
  • Include transient dependency fixes
  • Critical updates highlighted

Regular Updates

  • Routine dependency maintenance
  • Compatibility updates
  • Performance improvements

How Changes Are Managed

Zaojun uses uv-ship for automated changelog management:

  1. Commit changes: Make commits with clear, descriptive messages
  2. Create release: uv-ship automatically updates CHANGELOG.md with commit messages
  3. Review changelog: Verify automatic updates are correct
  4. Publish: Release is published to PyPI

Release Process

  1. Update version in pyproject.toml
  2. Create release with uv-ship (automatically updates CHANGELOG.md)
  3. Publish to PyPI

Finding Specific Changes

By Version

# Check what changed in a specific version
Look for "## [version]" heading

By Feature

# Search for feature-related changes
Use browser/search tool to find keywords

By Date

# Find changes by release date
Each version includes release date

Migration Guides

For significant changes, migration information is included:

Breaking Changes

  • Clear upgrade instructions
  • Backward compatibility notes
  • Migration steps

Deprecation Periods

  • Timeline for removal
  • Alternatives suggested
  • Upgrade paths

Security Advisories

Security-related changes include:

Vulnerability References

  • GitHub Security Advisory IDs (GHSA-xxxx-xxxx)
  • CVE references when available
  • Impact assessment

Update Recommendations

  • Urgency level
  • Update instructions
  • Workarounds if available

Current Version

  • Always check your current version first
  • Compare with latest release

Upgrade Instructions

  • Follow recommended upgrade paths
  • Test in development first

Support Timeline

  • No formal LTS releases
  • Regular maintenance updates
  • Security fixes as needed

Getting Update Notifications

PyPI

  • Watch package on PyPI
  • RSS feed for releases

Codeberg

  • Watch repository
  • Release notifications

Command Line

# Check for updates
zaojun --version
# Compare with latest on PyPI

Contributing to Changelog

When contributing to Zaojun:

  1. Write clear commit messages - these become changelog entries
  2. Use descriptive summaries - explain what changed and why
  3. Reference issues/PRs when relevant in commit messages
  4. Group related changes in logical commits

Examples

Simple Update

## `0.9.8` — [2026-02-14]
- Update dependencies versions. [c34d869]

Feature Release

## `0.9.7` — [2026-01-24]
### Added
- Support for dependency groups with `--groups` flag. [abc123]

### Fixed
- Handle network errors more gracefully. [def456]

Security Release

## `0.9.6` — [2026-01-10]
### Security
- Address vulnerability in transient dependency `urllib3` (GHSA-xxxx-xxxx). [ghi789]

Questions?

If you have questions about the changelog: - Check the repository issues - Review the contributing guidelines - Contact maintainers through Codeberg

See Also