Release Process

CensoredDistributions.jl follows a hybrid approach to release documentation, combining the Julia ecosystem's standard practices with a news file for major releases.

Release Philosophy

Release frequently: Ideally after every merged PR to main.
Semantic versioning: Follow SemVer strictly
Hybrid changelog approach: Use NEWS.md for major releases, GitHub releases for all releases
Automated tooling: Leverage standard Julia ecosystem tools
SciML ecosystem alignment: Follow established patterns from the broader scientific computing ecosystem

When NOT to release:

Work-in-progress features
Failing tests
Incomplete documentation for new features
During Julia ecosystem-wide changes (wait for stability)

Release Workflow

1. Standard Julia Tooling

We use the same tools as major Julia packages:

CompatHelper: Automated dependency updates via daily PRs
@JuliaRegistrator: Manual package registration to Julia General Registry
TagBot: Automated GitHub release creation after registry registration

2. Release Steps

For Regular Releases (Patch/Minor)

Ensure all tests pass and pre-commit hooks are clean

Update version in Project.toml:

version = "1.2.3"  # Follow semantic versioning

Commit and merge to main via PR
Trigger registration by commenting on the merge commit:
```
@JuliaRegistrator register
```
Automated flow:
- JuliaRegistrator creates PR to Julia General Registry
- Once merged (~15 minutes), TagBot automatically creates GitHub release
- Documentation is automatically deployed for new tagged versions

For Major Releases (Breaking Changes)

Plan breaking changes carefully with issue discussion
Create NEWS.md entry following the template above:
- Document all breaking changes with before/after examples
- Provide comprehensive migration guidance
- Include rationale for major changes
- Acknowledge significant contributors
Update version with major version bump (e.g., 1.5.2 → 2.0.0)
Follow same registration process as regular releases
Consider deprecation warnings in the previous minor release

Additional Major Release Considerations:

Create migration documentation or guides if needed
Update tutorials and examples to reflect new API
Coordinate with downstream packages that depend on CensoredDistributions.jl
Consider advance communication to user community via Julia Discourse or GitHub Discussions

3. Semantic Versioning Guidelines

Following SemVer:

Patch (1.0.0 → 1.0.1): Bug fixes, performance improvements
Minor (1.0.1 → 1.1.0): New features, additions to API (backwards compatible)
Major (1.1.0 → 2.0.0): Breaking changes to public API

Examples:

Adding new distribution types: Minor
Fixing calculation bugs: Patch
Changing function signatures: Major
Adding optional parameters: Minor
Removing deprecated functions: Major

4. Release Notes and Changelog Strategy

We use a hybrid changelog approach that combines the strengths of both traditional NEWS.md files and GitHub releases:

Changelog Hierarchy

GitHub Releases: Used for all releases (patch, minor, and major)
- Automatically generated by TagBo
- Provides immediate visibility in the Julia ecosystem
- Links to commits and PRs for detailed change tracking
NEWS.md: Used for major releases and significant milestones
- Provides comprehensive context for breaking changes
- Offers detailed migration guidance
- Follows SciML ecosystem conventions for major version documentation

Templates

Release Documentation Strategy

GitHub Releases (Minor/Patch - Automated):

GitHub automatically generates release notes for minor and patch releases
Uses commit messages and PR labels to categorise changes
No manual intervention required

NEWS.md Entries (Major Releases - Manual):

Maintainers manually write detailed entries for major releases
Focus on breaking changes, migration guidance, and significant features
Provide context
Follow a structured format with breaking changes, new features, and migration examples

NEWS.md Entry Template (Major Releases):

# CensoredDistributions.jl v2.0.0

## Breaking Changes

### API Restructuring
The distribution constructor API has been simplified and standardised:

**Before (v1.x)**:

julia d = PrimaryCensored(delaydist, primarydist, censoring_window)


**After (v2.0)**:

julia d = primarycensored(delaydist, primarydist; window=censoringwindow)


## New Features
- Unified distribution constructor interface
- Enhanced integration with Turing.jl v0.30+
- Support for arbitrary primary event distributions

## Performance Improvements
- 3x faster PDF calculations for common distribution pairs
- Reduced memory allocation in vectorised operations

## Acknowledgements
Special thanks to @contributor1, @contributor2 for major contributions to this
release.

5. Automation Details

CompatHelper

Runs daily via GitHub Actions (CompatHelper.yaml)
Automatically updates [compat] entries in Project.toml
Creates PRs for dependency version bumps
Helps maintain up-to-date dependencies across Julia ecosystem

TagBot

Triggered when package appears in Julia General Registry
Automatically creates GitHub releases with generated changelog
Uses SSH key (DOCUMENTER_KEY) for authenticated operations
Supports custom release notes if provided

Version Management Actions

Runs automatically on pushes to main checking for version changes in Project.toml
Accepts /version major|minor|patch comments on PRs from users with write permissions
Creates patch increment PRs for main branch or commits directly to PR branches