Start Contributing

Turing is an open-source project hosted on GitHub, and we’d love your help! Contributions of all kinds are welcome, whether that’s fixing a bug, writing a tutorial, improving the docs, or just reporting an issue you’ve run into.

If you’re not sure where to begin, feel free to ask on any issue, or come say hello in the #turing channel on the Julia Slack or Discourse.

What kinds of contributions are we looking for?

  • Bug reports and edge cases: If you run into something that doesn’t work, please open an issue! If you aren’t sure which repository to post on, don’t worry: just post it on the main Turing.jl repo and we can triage it.

    We’re especially keen on finding cases where automatic differentiation fails. If you find a model that doesn’t work with AD, please report it, and we can either help to report it upstream, and/or add it to the ADTests website.

  • Tutorials and example models: If you have an interesting model that you think others could learn from, we’d love to hear about it! You don’t have to write a full docs page immediately; just open an issue and we’d be very happy to chat about it.

  • Documentation improvements: Fixing typos, improving explanations, or even just suggestions for what new content to add are all very welcome.

  • Code contributions: Check the issue trackers for open issues, especially on Turing.jl and DynamicPPL.jl!

However, please don’t let these categories restrict you: please do feel free to open pull requests or issues for anything you think would be a useful contribution!

Overview of the TuringLang ecosystem

The Turing ecosystem really comprises a number of Julia packages. The most important ones to know about are:

  • Turing.jl is the top-level package that users interact with. It uses the functionality from the other packages to provide a user-friendly interface for probabilistic programming. Turing defines some of its own MCMC inference algorithms, but many of them are implemented by wrapping other packages (e.g. AdvancedHMC.jl).

  • DynamicPPL.jl is the ‘heart’ of Turing: it defines the modelling language itself and core operations on models. Currently, most active development work happens on DynamicPPL.

  • AbstractMCMC.jl is a lightweight package that defines an interface for samplers. If you’re implementing a new sampler, you should follow the API defined here.

  • Bijectors.jl, and specifically the Bijectors.VectorBijectors module, defines transformations between constrained and unconstrained parameter spaces.

If you’re looking to contribute documentation, do also check out our guide to documentation contributions, as that describes how Turing’s docs are structured.

New to Julia / open-source development?

If you are new to open-source, GitHub has a good introduction to the workflow, and Julia’s own contribution guide is also helpful.

We won’t cover all the details here as there are already a ton of good resources out there, but in short, you want to first fork the repository you want to contribute to. This will create a new repository under your own GitHub account: for example https://github.com/<MY_USER>/Turing.jl. You can then clone this repository to your local machine, make and commit your changes, and then push them back to your own fork on GitHub.

When developing Julia code, it is often very useful to work in an environment where you can add “development” versions of packages, which point to a local copy of the source code. A common workflow for Turing development is to clone all the requisite repositories (e.g. Turing.jl, DynamicPPL.jl, …) into a single directory, and use that enclosing directory as the location for a shared environment where you can add development versions of all the packages at once.

For example, let’s say you have cloned the Turing.jl and DynamicPPL.jl repositories to ~/turing/Turing.jl and ~/turing/DynamicPPL.jl respectively. Then, you can navigate to the ~/turing directory, and run:

julia --project=.

This will start Julia with the current directory as the active environment. Then, you can run:

] dev ./Turing.jl
] dev ./DynamicPPL.jl

That way, each time you restart your Julia session, you will pick up the latest changes from your local copy of the source code for both Turing.jl and DynamicPPL.jl.

You probably want to also use Revise.jl in conjunction with this, which allows you to skip the step of restarting Julia: simply edit code and the changes will be picked up automatically.

Back to top