CensoredDistributions.jl

Appearance

15

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: Use 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) ​

  1. Ensure all tests pass and pre-commit hooks are clean

  2. Update version in Project.toml:

toml
version = "1.2.3"  # Follow semantic versioning

  1. Commit and merge to main via PR

  2. Trigger registration by commenting on the merge commit:

@JuliaRegistrator register
  1. 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) ​

  1. Plan breaking changes carefully with issue discussion

  2. Create NEWS.md entry following the template above:

  • Document all breaking changes with before/after examples

  • Provide clear migration guidance

  • Include rationale for major changes

  • Acknowledge significant contributors

  1. Update version with major version bump (e.g., 1.5.2 → 2.0.0)

  2. Follow same registration process as regular releases

  3. 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 ​

  1. 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

  1. NEWS.md: Used for major releases and significant milestones

  • Provides 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): ​
markdown
# CensoredDistributions.jl v2.0.0

## Breaking changes

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

**Before (v1.x)**:

julia d = PrimaryCensored(delay_dist, primary_dist, censoring_window)


**After (v2.0)**:

julia d = primary_censored(delay_dist, primary_dist; window=censoring_window)


## 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

JuliaRegistrator ​

  • Community bot for registering packages

  • Only package collaborators can trigger registration

  • Validates package before creating registry PR

  • Usually completes registration within 15 minutes

7. Pre-release checklist ​

Before triggering @JuliaRegistrator register:

For All Releases:

  • [ ] All CI tests pass (including pre-commit hooks)

  • [ ] Version number follows semantic versioning

  • [ ] New features have tests and documentation

  • [ ] Dependencies are up to date (check CompatHelper PRs)

  • [ ] Examples in docstrings work correctly

Additional Checklist for Major Releases:

  • [ ] NEWS.md entry created following template

  • [ ] Breaking changes documented with migration examples

  • [ ] Deprecation warnings added in previous releases (where applicable)

  • [ ] Migration guide or documentation updated

  • [ ] Downstream package compatibility assessed

  • [ ] Community communication planned (if needed)

8. Emergency releases ​

For critical bug fixes: 2. Create hotfix branch from latest release tag

  1. Apply minimal fix with tests

  2. Bump patch version immediately

  3. Fast-track PR review and merge

  4. Register immediately with @JuliaRegistrator register

9. Coordinating with Julia ecosystem ​

Registry compatibility ​

  • Monitor Julia ecosystem releases affecting dependencies

  • Test against Julia LTS, stable, and pre-release versions in CI

  • Follow Julia deprecation cycles

Documentation releases ​

  • Major releases trigger documentation rebuilds automatically

  • Ensure tutorials work with new versions

  • Update installation instructions if Julia version requirements change

10. Troubleshooting releases ​

Common issues: ​

  • Registry PR fails: Check Project.toml syntax and version conflicts

  • TagBot doesn't trigger: Verify DOCUMENTER_KEY secret is configured

  • Tests fail after release: Emergency patch release procedure

Getting help: ​

  • Check Julia Discourse for registry issues

  • SciML community practices for guidance

  • GitHub Issues for package-specific problems

This process ensures reliable, frequent releases while maintaining high quality and ecosystem compatibility.