3  How to contribute to Stan?

By the end of this section, you will know the different ways of contributing to Stan, from engaging on Stan Discourse, over filing bug reports and feature requests, writing documentation and case studies, to contributing code. You will know how to pick a contribution path that fits you, write a clear GitHub issue or pull request, and follow project norms.

Important

You don’t need to be a professional software developer or statistician in order to contribute to Stan!

3.1 Types of contributions

There are many ways to contribute to Stan, including:

3.2 Typical workflows for contributing

3.2.1 Participate in the Stan Discourse

  • Stan Discourse is the main forum for users and developers to ask questions, discuss issues, and share ideas.
  • We aim to keep this a friendly and welcoming space, guided by our:
  • We also discuss topics on Slack, but we encourage users to ask questions on Stan Discourse instead as it’s open to everyone, so answers can help other community members too.

3.2.2 Feature requests and bug reports

  • Go to the GitHub repository you want to contribute to.
  • Get familiar with its Issues and PRs (e.g., loo).
  • If you’re a new contributor:
    • Look for labels like “help wanted” or “good first issue.”
    • Avoid issues that involve refactoring or larger changes.
    • When in doubt, ask in the issue whether it’s a good one to work on.
  • To open a new Issue:
    • First check whether it already exists, to avoid duplicates.
    • Some tips for writing good Issues…
NoteWriting good Issues: Bug Report
  • Title: One sentence, specific, searchable.
  • Body
    • What happened vs what you expected
    • Minimal reproducible example (i.e., small model/script/data that triggers the problem)
    • (Optional) Environment: OS, hardware if relevant
    • Exact steps to reproduce the problem.
    • Logs / error output (if possible as text in a code block, not a screenshot, so it’s searchable)
  • Examples:
NoteWriting good Issues: Feature Request
  • Title: One sentence, specific, searchable.
  • Body
    • describe the problem or limitation
    • (optional) propose solution
    • (optional) note scope of Issue: small, self-contained or does it open a design discussion?
  • Examples:

Additional references:

3.2.3 Feedback on documentation

  • Clarifying confusing sections
  • Adding examples or code snippets
  • Fixing inaccuracies (e.g., when current behavior deviates from documented behavior)
  • Flagging content that is missing or unclear
  • Fixing typos, grammar, and broken links

3.2.4 Contributing a case study or tutorial

NoteChecklist for contributing a case study

1. Initial contact

2. Content requirements

  • write it as a narrative document, not just code
  • use a reproducible-notebook format
  • note exact software and compiler versions used
  • fix random seeds so results are exactly reproducible
NoteChecklist for contributing a case study (continued)

3. Licensing

  • license code under an open source license (e.g., BSD or GPL)
  • license text as Creative Commons (CC-BY is most common)
  • author retains copyright (but Stan needs to be permitted to host and redistribute)

4. Metadata for published case study

  • Title and Author(s) (optional affiliation)
  • Short abstract/description (in 2-4 sentences, what problem is solved and why it matters)
  • Keywords (3-6 terms for discoverability)
  • Source repository link (e.g., a public GitHub repo containing the actual notebook/knitr source, separate from the rendered HTML)
  • Dependencies list (package/library versions used)
  • Rendered HTML version (the actual output others will read)

3.2.5 Contributing Code

Some packages have templates others don’t, but overall a good PR description should incorporate the following information:

NoteWriting a good PR description

Before you start:

  • Have you read the contributing guidelines and AI Contribution Policy?
  • Contributing to Stan core libraries (e.g., stan, math, stanc3)? Checkout Developer Wiki?
  • Is your PR small and focused on one logical change?
  • Not ready for review yet? Open it as a Draft PR so reviewers know to hold off.

Title: One sentence, specific, searchable.

  • Good: Fix incorrect ESS calculation for thinned chains
  • Avoid: Bug fix
NoteWriting a good PR description (continued I)

Body:

Description

  • Describe what has been changed and why.
  • Be concise and use your own words (try to avoid using AI-generated text).
  • Add any uncertainties or open questions you have here as well.

Breaking changes: Does this PR change existing behavior, APIs, or output? If yes, describe the impact.

Tests: (if applicable) Which tests have you added?

Documentation / Vignettes: (if applicable) Have you added documentation?

NoteWriting a good PR description (continued II)

Checklist

  • Style is consistent with existing code and docs
  • Documentation or vignette renders locally
  • Tests and devtools::check() pass
  • NEWS.md entry added
  • If you used an AI assistant, please disclose and review changes critically
  • For the full checklist, see checklist

TODOs: List any remaining tasks you need to complete before the PR is ready to be merged.

Examples:

3.2.6 Some reflections on the use of AI-assisted development

  • Stan AI Contribution Guideline
  • Use your own words when writing the PR description and comments in a PR review process
  • Review all changes made by an AI assistant critically and ask yourself:
    • Is this change correct?
    • Do I need this change?
    • Is this change in the scope of the PR?
  • When in doubt about something, ask rather the Stan developers than the AI assistant