Contributing

PRISM fellows and collaborators contribute through focused branches and reviewed pull requests. Ask a maintainer before making a large structural change or changing authorship, licensing, or publication policy.

Note

Discuss authorship and contributor credit early. A merged contribution does not by itself determine author order or authorship.

1. Create a focused branch

Start from an up-to-date main branch and use a short, descriptive branch name:

git switch main
git pull --ff-only
git switch -c initials/short-description

Keep unrelated edits in separate pull requests. Never commit credentials, private correspondence, reviewer material, session notes, or local agent artifacts.

2. Edit the publication

  • Write the main narrative in index.ipynb.
  • Put reusable analysis code in src/analysis/.
  • Add BibTeX records to ref.bib and cite them in the manuscript with Quarto citation syntax.
  • Update authors.yml when the working author roster changes.
  • Do not change the Warm Journal default or either publication theme during a writing contribution.

3. Record contributions and AI use

Before release, the team must complete both processes:

  • Follow the CRediT contribution guide. The issue form records the ordered roster, all 14 CRediT roles, and author approval.
  • Complete ai-use.yml according to the AI usage guide. Every first and last author supplies an exact statement. Every other author reads the full disclosure and confirms that review.

Keep ai-use.yml at status: draft while statements are incomplete. Change it to complete only after the required authors have reviewed the generated disclosure.

4. Preview and test

Preview both supported presentations of the same content:

make preview-warm
make preview-technical

Before requesting review, run:

make test
make render-warm
make render-technical

If code-cell results changed intentionally, run make execute and include the relevant _freeze/ updates. Review the rendered narrative, figures, citations, links, author display, and AI disclosure.

5. Open a pull request

Push your branch and open a pull request into main. In the description:

  • summarize the scientific or editorial change;
  • identify any new data, dependencies, or generated outputs;
  • list the checks and previews you ran;
  • flag decisions that still need author or maintainer review; and
  • request review from the appropriate mentor or collaborator.

Respond to review comments on the same branch. Do not resolve scientific disagreements by silently rewriting another author’s claims; discuss them in the pull request.

6. Publication

After review, a maintainer merges the pull request into main. GitHub Actions then rebuilds the site and updates the public project publication. Releases and Zenodo deposits are separate, deliberate milestones; a routine merge does not create a DOI.