Skip to content

CONTRIBUTING

Contributing to Particula

Thanks for thinking about contributing! Our goal is to make your first pull request (PR) smooth—whether you are brand‑new to open‑source or a seasoned developer.

1. Choose the Right Path

You are… Start here
Experienced with Git + Python Jump straight to Github workflow below.
New to GitHub or virtual‑envs Follow setup for new contributors and the Contributor Setup guide.
Planning to contribute major code or new features Follow Feature Workflow and Code Specifications before you begin.

2. Setup for New Contributors

For the complete, click‑through tutorial (fork → clone → virtual‑env → editable install) see the Contributor Setup guide.

If you already have Python, Git, and a preferred editor, skim this section.

  1. Install Git & VS Code
  2. Git: https://git‑scm.com/downloads

  3. VS Code: https://code.visualstudio.com/ (recommended extensions: Python, GitHub Pull Requests & Issues).

  4. Fork the repository
    Click Fork on https://github.com/uncscode/particula. This creates yourname/particula.

  5. Clone your fork

    git clone https://github.com/<your‑username>/particula.git
cd particula

  6. Create a virtual environment (pick one)

Tool Command Instructions
uv (fast, minimal) uv venv .venv
source .venv/bin/activate
uv pip install -e ".[dev,extra]"		 uv setup guide
pip + venv python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,extra]"		 pip setup guide
conda conda create -n particula-dev
conda activate particula-dev
pip install -e ".[dev,extra]"		 conda setup guide
  1. Verify installation
    pytest -q    # all tests should pass
particula --help

3. GitHub Flow

Step What you do Why
1 Fork → Clone → Set up .venv → pip install -e ".[dev,extra]" Gives you a local, editable checkout with all dev tools.
2 Sync with upstream
(keeps your main current)		 Avoids merge conflicts later.
3 Discuss your feature Helps us understand your goals and avoid duplication of effort.
4 Theory → Code → Test → Examples Adds value without breaking existing functionality.
5 Commit + Push to your fork Publishes your branch to GitHub.
6 Open a Pull Request to uncscode/particula Starts the review & CI pipeline.
7 Discuss & Iterate with reviewers Polishes the contribution.
8 Rebase (done by maintainer) Your code lands in main.
9 Celebrate 🎉 You just helped improve Particula!

Expanded GitHub Flow

Step 1 – Fork → Clone → Environment

See setup guides above for details.

Step 2 – Sync your fork with upstream (repeat as needed)

git remote add upstream https://github.com/uncscode/particula.git   # one‑time
git checkout main
git pull upstream main
git push origin main

Step 3 – Discuss your feature

If you are planning a large feature or change, please open a Discussion first. This helps us understand your goals and avoid duplication of effort. Or if you are new to the project, ask for guidance in the GitHub Discussions.

If you have experience with the codebase and it is a small change, you can skip this step. Pure bug fixes or small features or new examples are usually fine to skip this step too.

Step 4 – Theory → Code → Test → Examples

For a full step‑by‑step breakdown see the Feature Workflow guide and the Code Specifications.

  • Create feature branch (e.g., issue123-fix-simulation).
  • Add/adjust new code or documentation.
  • Add/adjust tests.
  • Add/adjust docstrings & markdown pages.

Step 5 – Commit & push

For an overview of git standards we use, see Linear Git Repository.

git add .
git commit -m "FIX #123: timestep rollover in simulation"
git push -u origin issue123-fix-simulation

Step 6 – Open a Pull Request

  • Go to your fork → Compare & pull request.
  • Fill in the PR template; mark as Draft for early feedback if desired.

Step 7 – Discuss & iterate

  • GitHub Actions runs tests (pytest -Werror), Ruff validation, type checks, and docs build automatically.
  • Push additional commits to the same branch—CI re‑runs and the PR updates.

Step 8 – Rebase
When CI is green and reviews are approved, a maintainer will merge-rebase your PR into main.

Step 9 – Celebrate! 🎉
Your contribution is now part of Particula—thank you!

4. Coding Standards & Review Expectations

Topic Rule
Style Detailed rules: Code Specifications.
Docstrings Follow the templates in Function docstring format and Class docstring format. One‑line summary + details + sections (Arguments, Returns, Raises, Examples, References).
Typing Use typing annotations. Omit types in docstrings.
Tests Every public function/class must have at least one pytest test. Add regression coverage for fixes and keep change-scope coverage strong. See Add Unit Tests and the testing guide.
Commit messages Imperative mood, ≤ 72 chars summary + context body if needed.
Large changes Open a discussion first and discuss design before implementation.

5. Common Commands

one‑liners you can copy‑paste

Purpose Command
Quick unit tests pytest -q -Werror
Coverage check pytest --cov=particula --cov-report=term-missing
Ruff auto-fix lint ruff check particula/ --fix
Ruff format ruff format particula/
Final Ruff check ruff check particula/
Static type-checking mypy particula/ --ignore-missing-imports

CI note: Every pull request triggers GitHub Actions (Ubuntu / macOS / Windows).
The local validation path should mirror the current repository workflow: run ruff check particula/ --fix, ruff format particula/, ruff check particula/, mypy particula/ --ignore-missing-imports, and the relevant pytest command for your change scope (plus coverage when needed).
Any warning promoted to an error (via -Werror) or other failure marks the PR ❌. Click “Details →” beside the failing job to view logs, fix locally, push again, and the checks will re‑run automatically.

GPU validation note: Use the testing guide and GPU roadmap as the canonical policy for Warp-targeted validation. Focused Warp CPU runs are the default supported path, CUDA runs are optional/local/manual only, and missing-Warp or missing-CUDA cases should surface as expected skips rather than CI failures. For targeted local runs, use marker selection such as -m "warp and gpu_parity" or -m "warp and cuda".

6. Need Help?

  • Questions: open a “Discussion” or tag a maintainer in your PR.
  • Stuck on Git? Try git status, git restore, or ask for pairing in the chat.
  • Broken tests on CI? Click “Details” next to the failing job; logs usually point to the exact line.

We appreciate every contribution—code, docs, tests, or ideas. Welcome to the Particula community! 🎉