Contributing to Celeritas

Thank you for your interest in the Celeritas project! Although Celeritas is developed primarily by a group of U.S. Department of Energy subcontractors, our goal is to increase community involvement and integration over time. We welcome your contributions!

Copyright

All submissions to the Celeritas project are automatically licensed under the terms of the project copyright as formalized by the GitHub terms of service. The person who writes a line of code is its author and copyright holder, but the new code should be the shared responsibility of the project rather than the exclusive property of a single contributor. Celeritas is a collaborative project with collective ownership.

AI-authored and -assisted pull requests

As of the year 2026, automated agentic software development tools have advanced to the point of providing considerable utility for large software projects. They can greatly accelerate the implementation of new features and code refactors. However, because the underpinning Large Language Models (LLMs) are essentially optimized for generating plausible output in large quantities, they can generate code that is (1) incorrect or superfluous while superficially seeming necessary and (2) unnecessarily complex/verbose. For this reason, and for ethical considerations, we make three requirements:

• Pull requests with substantial code additions/changes performed by AI agents must clearly note this in the description, and/or tagged with the ai-assisted label.

• AI-assisted code commits must be tagged with an Assisted-by trailer (see AGENTS file)

• Every pull request to Celeritas must be submitted in draft mode with a human in the loop.

• The submitting person must perform a review of the submitted code before marking the PR as “ready.”

Attribution

You will get public credit for your work: your username and pull requests will be listed in the release notes, and you will receive official co-authorship on the Zenodo code object for the next major (and minor, if your fix is backported) releases that incorporate your contribution. By contributing, you acknowledge the attribution and authorship policy laid out in Authorship and attribution.

Note

To uniquely link your contribution for the next release, you must add your ORCID to scripts/release/users.json to your first PR. (Otherwise, only your GitHub-derived name will show on the record.) If you want the release to be automatically propagated to your ORCID account, you must sign up for and connect it to OpenAIRE.

Collaborating

Working with other Celeritas team members is a critical part of the development process. Please join the #code channel on the Celeritas Slack workspace, or open an issue with a bug report or feature request.

Development prerequisites

Create a fork of the Celeritas repository. You should clone this fork locally to your development machine as the “origin”, and it’s a good idea to add the main celeritas-project repository as an “upstream” so that you can merge changes from the main codebase as you work.

To meet the Formatting requirements described in the development guide, you must install the pre-commit utility. You can run scripts/dev/install-commit-hooks.sh to do this.

A mostly consistent set of decorations (separators, Doxygen comment structure, etc.) are used throughout the code, so try to make new files look like existing ones. Use the celeritas-gen.py script (in the scripts/dev directory) to generate skeletons for new files, and use existing source code as a guide for how to structure the decorations.

Submitting code changes

When you believe that you’ve made a substantive [1] and self-contained improvement to the code, it’s time to create a pull request (PR) to get feedback on your changes before they’re merged into the code base. The pull request should be as close to a “single change” as possible (i.e., the short pull request title can essentially describe the entire change set), typically a few hundred lines (not including tests and test data). A pull request could be as small as a single line for a bug fix. If your changes involve both substantial refactoring and new features, try to split the refactoring into a separate commit.

Before opening the pull request, check that the code and style guidelines have been followed for all new code and code changes. Ensure the use of the correct formatting as well as the addition of documentation and unit tests for new code and bug fixes.

After opening the pull request, the pre-commit.ci bot will run automatically and check your formatting. If it fails, you probably did not install the utility mentioned in the previous section. You can git pull the suggested changes and then install pre-commit; or, if you’ve made changes locally, then install pre-commit, you can execute pre-commit run --from-ref upstream/develop --to-ref HEAD and git push -f to update all files and force push.

All tests must pass on the CI runner before a PR can be merged. It’s best to test locally first before submitting your pull request, and keep in mind that the multiple configurations on the CI (different dependency versions, different features) may reveal failures that your local testing might have missed.

Each pull request should be assigned one or two reviewers who will provide constructive feedback on your changes. Their responsibilities are outlined in Code review. Reviews should not be started until the “draft” status has been removed (if you marked it as a draft initially). Once a pull request is under review, do not rebase, squash, or otherwise alter the branch history. Such changes can drastically increase the difficulty of reviewing, because it may blend in a single commit both changes in response to a review and changes from upstream code. (Furthermore, it breaks GitHub notifications and makes it more difficult to find older comments.) You can merge the main upstream branch if your changes may interact with the upstream changes, and you must merge if they conflict.

The review is complete and your branch will be squashed and merged when:

• All the CI tests pass,

• All conversations have been resolved [2], and

• The reviewer has approved the changes.

And you will officially be a Celeritas contributor! Congratulations!

[1]

All changes to the codebase must go through the pull request, but due to the overhead of reviewing, testing, merging, and documenting a PR, we’d like to avoid small changes that have almost no effect in terms of operation or readability. For example, if you find a typo in the documentation, check the rest of the docs for any other typos or improvements you’d like to make, and submit a single PR with those changes.

[2]

When you’ve fully implemented the reviewer’s comment, you may mark it as resolved without commenting. Do not resolve a conversation if you disagree with the feedback: instead, post your view in a follow-on comment and wait for the reviewer to respond. If you comment, whether to supplement your change or to iterate with the reviewer, please do not resolve the conversation since that makes it hard to find your comment.

Pull request style

Title

The title should be an imperative statement (title-cased first word, no trailing punctuation) summarizing the PR’s effect on the user. These titles are copied directly into the release notes. For example:

• Implement the FooBar model

• Handle errors in track initialization

• Fix sampling of low-energy Celeritons

• Refactor code in preparation for new tracker type

• Add CI support for multiple Geant4 versions

Do not add textual or emoji tags to the title (e.g., no CI: or 🐛).

Description

The description should summarize or enumerate the main changes in the pull request. Illustrative images (flow charts, performance plots) make excellent additions.

Draft status

Submit your pull request as a draft if you want to run further testing before beginning the review process. The “Create pull request” button has a drop-down menu arrow that lets you select “Draft pull request”. Any PR with AI-assisted changes must be opened in draft mode with a human in the loop before marking it ready for review.