Contributing Guidelines

We are excited that you are interested in contributing to Ptera Software! This guide will help you get started. If you have any questions not answered here, please open a new discussion and we will respond.

Before Contributing

Please review the following documents before making contributions. These documents are also available on the Ptera Software documentation website.

  1. README

  2. Code of Conduct

  3. Security Policy

  4. License

Ways to Contribute

There are three main ways you can contribute:

  1. Report a bug

    • Identify and document issues that prevent Ptera Software from working as expected.

    • This includes errors, crashes, incorrect outputs, or unexpected behavior.

  2. Request a feature

    • Suggest new features, improvements to existing functionality, or usability changes.

    • This can be small quality-of-life improvements or larger feature proposals.

  3. Contribute code

    • Submit changes that add new features, fix bugs, improve performance, or enhance documentation.

    • Code contributions can address your own ideas or work on existing open issues.

    • If you find an issue labeled good first issue that you want to work on, comment on the issue to claim it before starting work. This prevents duplicate efforts.

Reporting a Bug

If the bug is a security vulnerability, do not post it as a public issue. Follow the security policy instead.

For all other bugs:

  1. Search the issues page to check if it’s already been reported.

    • If it exists, you can comment or add an emoji reaction to indicate that you are also affected.

  2. If it has not been reported, open a new issue using the bug report template.

  3. Add the bug label plus any others that apply.

Requesting a Feature

For feature requests:

  1. Search the issues page to avoid duplicates.

    • If it exists, comment or react to indicate interest.

  2. If it has not been requested, open a new issue using the feature request template.

  3. Add the feature label plus any others that apply.

Contributing Code

Ptera Software now uses GitHub Flow to manage code contributions. If this is new to you, it’s a good idea to read through this guide first. Once you understand the process, here’s how to implement it:

  1. Choose what to work on

    • Look for issues labeled good first issue.

      • If you want to work on one, check that no one else has already commented claiming it. If unclaimed, comment on the issue to claim it and a maintainer will then “assign” the issue to you.

      • If you want to work on a claimed issue that hasn’t been updated in a while, write a comment asking if the user who originally claimed it is still actively working on it.

    • If you have your own idea, search the issues to ensure it hasn’t already been proposed.

      • If you can’t find anything, you could open a new issue describing your change and state that you will be implementing it. This step isn’t strictly required, but it is recommended for first-time contributors.

    Coordination on In-Progress and Draft Work

    Some issues and pull requests (PRs) may represent work that is actively under design or refinement.

    If a PR exists, or if an issue has been assigned to or claimed by someone else, please do not start parallel implementation work without first checking in via a comment. A short message like “Are you still actively working on this?” or “Is this a good time to help with X?” is usually sufficient.

    This helps avoid duplicated effort and ensures that contributions align with the current design direction.

  2. Set up your local environment

    • Fork the repository on GitHub to your own account.

    • Clone your fork to your local machine:

    git clone https://github.com/<your-username>/PteraSoftware.git
cd PteraSoftware

    • Add the main repository as a remote named upstream so you can keep your fork up to date:

    git remote add upstream https://github.com/camUrban/PteraSoftware.git

    • Create a virtual environment and install dependencies for development. Note that Ptera Software requires Python 3.11, 3.12, or 3.13 (3.13 is recommended):

    python3 -m venv .venv # On Windows use python instead of python3
source .venv/bin/activate # On Windows use .venv\Scripts\activate
python3 -m pip install --upgrade pip # On Windows use python instead of python3
pip install -r requirements.txt # Install dependencies for running simulations
pip install -r requirements_dev.txt # Install dependencies for development (e.g. black, codespell, etc.)
pip install -e . # Install the package in editable mode
pre-commit install # Install git hooks for automatic code formatting checks
deactivate

    Note: If you use PyCharm, the repository includes a pre-configured .idea directory with code style settings and inspection profiles. If you use Claude Code, the repository also includes a pre-configured CLAUDE.md file and a .claude directory with permission and sandbox settings.

    PyCharm Setup

    The repository tracks a small set of .idea/ files for shared code style and inspection settings, and PyCharm rewrites them on your machine whenever you open the project. To keep these local rewrites out of your commits, run two commands once from the project root after cloning.

    First, add .idea/ to your personal exclude file so any new .idea/ files PyCharm creates do not appear in git status. This file lives only in your clone and is never committed:

    echo ".idea/" >> .git/info/exclude

    Second, mark every currently-tracked .idea/ file with skip-worktree so PyCharm rewriting them does not appear in git status either. Run this in a shell that supports pipes (Git Bash on Windows, Terminal on macOS, or any Linux shell):

    git ls-files .idea/ | xargs git update-index --skip-worktree

    The tracked .idea/ files remain in the repository, but local modifications to them are ignored. Before opening a PR, confirm that git status does not list anything inside .idea/.

    If a future pull from upstream/main legitimately updates one of the tracked .idea/ files, git pull will refuse with an error like:

    error: Your local changes to the following files would be overwritten by merge:
        .idea/<some-file>
Please commit your changes or stash them before you merge.
Aborting

    If every file listed in the error is inside .idea/, discard your local versions (PyCharm will rewrite them the next time you open the project) and pull again:

    git checkout HEAD -- .idea/
git pull

    If any listed file is outside .idea/, stop and ask in a discussion before running anything else.

    Pre-commit Hooks

    The hooks in .pre-commit-config.yaml are SHA-pinned with # frozen: <tag> comments, so Dependabot can manage bumps with a 7-day cooldown that gives the community time to catch a malicious release before it reaches us. Do not run pre-commit autoupdate directly: it rewrites every rev: field back to a moving tag and undoes the pinning.

  3. Create a new branch

    • Branch from main for each change.

    • Use descriptive branch names, such as feature/add_new_plot or bug/fix_units.

    git switch main
git switch -c <branch_name>

  4. Make your changes

    Other Guidelines

    Depending on what you’re working on, the following documents may also be helpful:

    Core Modeling Contributions

    Some parts of Ptera Software, such as the UVLM formulation, wake evolution, force and moment integration, and related aerodynamic models, are closely tied to underlying theoretical assumptions and numerical constraints.

    Contributions in these areas are very welcome, but they typically require coordination and shared understanding of the relevant aerodynamics. When opening a PR that touches core modeling logic, please:

    • Clearly describe the physical assumptions being made.

    • Note the regime in which the change is expected to be valid.

    • Include references, derivations, or reasoning where appropriate.

    • Add tests that validate the behavior against known physical expectations (e.g., symmetry, limiting cases, conservation behavior).

    If you’re unsure whether a change falls into this category, feel free to ask in the issue or PR thread before investing significant effort.

  5. Commit your work

    • Run automated checks locally:

    source .venv/bin/activate # On Windows use .venv\Scripts\activate
pre-commit run --all-files
mypy pterasoftware
python -m unittest discover -s tests

    • If the checks pass, check which files you’ve modified:

    git status

    • Stage the changes you’d like to commit:

    git add <file-1> <file-2> ...

    • Before committing, note that you need to know how to use Git’s text editor, which defaults to Vim. If you’ve never used Vim before, I recommend telling Git to use Nano instead, as many people find it less confusing. To do so, run the following (you only need to run it once):

    git config --global core.editor "nano"

    • Now, commit your changes:

    git commit

    This will open Nano, where you enter your commit message above the commented out # lines. Please follow best practices for commit messages. Below is a lightly adapted version of Tim Pope’s famous sample commit message:

    Capitalized, short (50 chars or less) summary

More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body. The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.

Write your commit message in the imperative: "Fix bug" and not "Fixed
bug" or "Fixes bug." This convention matches up with commit messages
generated by commands like git merge and git revert.

Further paragraphs come after blank lines.

- Bullet points are okay, too

- Typically a hyphen or asterisk is used for the bullet, followed by a
  single space, with blank lines in between, but conventions vary here

- Use a hanging indent

    Once you are satisfied with your commit message, enter Ctrl+O and Ctrl+X to save and exit, which will trigger the commit. Alternatively, with an empty commit message, enter Ctrl+X to exit and abort the commit.

  6. Push your changes and open a PR

    • Push your branch to your fork:

    git push -u origin <branch-name> # After the first push, just use git push

    • Open a PR from your branch to the main branch of the upstream repository.

      • You can open the PR as a Draft to get feedback early before the work is complete. Draft PRs indicate that design details may still be changing.

      • In the PR description, follow the PR template, and link any related issues.

  7. Keeping your branch up to date

    • If main changes before your PR is merged, sync your branch to avoid merge conflicts:

    git fetch upstream
git merge upstream/main

  8. Review and approval process

    • Only the repository owner (currently camUrban) can approve merges to main.

    • Your PR will be reviewed, and changes may be requested.

    • Once approved, it will be merged into main and included in the next release.

Release Process

Ptera Software follows SemVer conventions for release naming and uses GitHub Flow for branching. Releases include a version bump and deployment to GitHub and PyPI once every few months, plus on-demand releases for critical bug fixes.