Pull Requests, Versions, and Releases

Don’t worry about getting everything right on your first PR — we’re happy to help you through the process. Even an imperfect or half-finished PR is welcome; it’s often easier to discuss changes with code in front of us.

Once you open a PR, someone from the dev team will review your code (if they don’t, ping @TuringLang/maintainers in a comment to get their attention). If all looks good, we’ll merge it. If not, we’ll help you fix it and then merge it.

Which branch should I target?

All TuringLang repositories follow semantic versioning; however, the way we manage this differs between repositories.

Turing.jl and DynamicPPL.jl retain two long-lived branches: main and breaking.

When choosing a target branch for your PR, consider whether your change is breaking:

  • main is for non-breaking changes: bug fixes, new features that don’t change existing behaviour, documentation, etc.
  • breaking is for changes that lead to incompatibilities with previous versions’ public API. Because we don’t like introducing breaking changes too frequently, we tend to aggregate multiple breaking changes into a single release. This is why we have a separate breaking branch: it allows us to merge breaking changes as they come in without having to wait for a release.

If you’re unsure about whether your change is breaking, just let us know in the PR: we can help you figure it out.

Other repositories don’t have separate main and breaking branches. In this case, if you have a breaking change, just target main and make sure to increment the appropriate version in the Project.toml file (see below).

Version numbers

For packages which have a version number of 0.x.y:

  • If the change you’re making is non-breaking, you should increment the patch version (the last number) in the Project.toml file. For example, 0.3.4 would go to 0.3.5.

  • If it’s a breaking change, you should increment the minor version (the middle number) and reset the patch version to zero. For example, 0.3.4 would go to 0.4.0.

For packages which have a version number of 1.x.y or higher:

  • If you are only providing a bug fix, and not introducing any new features, you can increment the patch version (the last number) in the Project.toml file. For example, 1.2.3 would go to 1.2.4.

  • If you are introducing new features but not breaking any existing functionality, you should increment the minor version (the middle number) and reset the patch version to zero. For example, 1.2.3 would go to 1.3.0.

  • If you are introducing breaking changes, you should increment the major version (the first number) and reset the minor and patch versions to zero. For example, 1.2.3 would go to 2.0.0.

Changelogs

When you make a PR, please add an entry to HISTORY.md describing the change. You can see existing entries for examples of the style.

If you are working on a repo that does not already have a HISTORY.md file, please consider creating one at the root of the repository! A changelog that’s started late is still better than no changelog at all.

What happens after I open a PR?

Code review

A maintainer will review your code. This is a collaborative process: don’t worry if you get comments or change requests, that’s normal and expected.

CI checks

We run the test suite in GitHub Actions for several Julia versions. Generally, all tests and code formatting checks should pass before merging.

If the formatting check fails, please follow the instructions on the Code Formatting page to fix it.

Some CI checks are allowed to fail:

  • Julia prereleases: These inform us of upcoming issues but don’t block merging.

  • Code coverage: It’s often helpful to inspect these, but we don’t enforce specific coverage numbers.

  • Upstream bugs: Occasionally CI fails due to issues in dependencies or base Julia. A good indicator is if the same test fails on the base branch too. Do ping a maintainer if you’re unsure about whether a CI failure is expected.

Back to top