Contributing to This Project¶

Purpose ¶

This document defines the rules and expectations for contributing to this project. Participation in contributions, including but not limited to issues, pull requests, documentation, or other code submissions, constitutes acceptance of these terms.

Contributions are voluntary and made at the contributor’s own risk. The maintainers reserve exclusive authority over all contributions.

Project Philosophy ¶

This project values:

Code clarity over cleverness.
Strong typing and static analysis.
High test coverage.
Explicit over implicit behavior.

Quick Start ¶

Fork the repository.
Clone your fork locally.
Open the project in VS Code using Dev Containers.
Install pre-commit hooks:
```
pre-commit install
```
Create a branch from test.
Make your changes and add tests.
Run:
```
nox -t test
```
Open a pull request targeting test.

CI Status ¶

All pull requests must pass the automated CI checks before review.

General Guidelines ¶

All contributions must:

Follow the coding, formatting, and documentation standards defined in the project.
Be submitted in accordance with the branching and pull request process, if applicable.
Be relevant, constructive, and in good faith.
Comply with applicable laws and the Code of Conduct.

Submissions that do not meet these criteria may be rejected without explanation.

Security and Sensitive Issues ¶

Do not submit security vulnerabilities through issues or pull requests. All security-related concerns must be reported according to SECURITY.md.

Failure to follow the security reporting procedure may result in rejection of the submission.

Scope of Contributions ¶

The maintainers reserve the right to:

Accept, reject, or modify contributions at their sole discretion.
Define which versions or branches are supported for contributions.
Disregard contributions that are outside the intended scope or violate security or conduct policies.

No commitment is made to merge contributions, respond to submissions, or provide ongoing support.

No Compensation or Liability ¶

Contributors acknowledge and agree that:

No compensation or credit is guaranteed beyond attribution in commits or documentation.
All contributions are provided “as is”.
Maintainers and the developer disclaim all liability for any damages, losses, or consequences arising from submitted contributions.

Reporting Issues ¶

General issues unrelated to security may be reported through Issue Tracker. Reports must be relevant, clear, and reproducible to be considered.

When filing an issue, make sure to answer these questions:

Which operating system and Python version are you using?
Which version of this project are you using?
What did you do?
What did you expect to see?
What did you see instead?
Any details about your local setup that might be helpful in troubleshooting
An effective way to get your bug fixed is to provide a test case, and/or steps to reproduce the issue.

Security-sensitive reports must only follow the SECURITY.md reporting process.

Fixing Issues ¶

Look through the Issue Tracker for bugs. Anything tagged with bug and help wanted is open to whoever wants to fix it.

Request Features ¶

Request features on the Issue Tracker.

If you are proposing a new feature:

Explain in detail how it would work.
Keep the scope as narrow as possible, to make it easier to add.

Implement Features ¶

Look through the Issue Tracker for features. Anything tagged with enhancement and help wanted is open to whoever wants to Add it.

Development Environment ¶

Use VS Code Dev Containers extension and clone this repository.

Requirements will be installed automatically

Poetry manages virtual environments and dependencies for this project.

pre-commit manages linters, static analysis, and other tools for this project.

Install pre-commit hooks after cloning, run:

pre-commit install

Using pre-commit ensures PRs match the linting requirements of the codebase.

Install vcxsrv on your local machine to enable GUI applications from the dev container.

Open vcxsrv and configure it with the following settings:

Multiple windows
Start no client
Disable access control

Or load it with config.xlaunch file from .devcontainer/vcxsrv/ directory.

PySide6 is used for UI development, run pyside6-designer from the dev container terminal to open the Qt Designer application.

Convert the output .ui files to .py files using the following command: .. code-block:: sh

pyside6-uic path/to/input.ui -o path/to/output.py

Possible issues ¶

If you encounter an error about not setting user.name and user.email for committing with git:

Run the following commands on your local machine terminal to set-up your git connection

git config --global user.name "YOUR_USER_NAME"

git config --global user.email "YOUR_EMAIL"

Rebuild the container

If you encounter an error about not having the permission to .git/object for committing with git: insufficient permission for adding an object to repository database .git/objects

Run the following commands on dev container terminal:

sudo chmod -R a+rwX .

sudo find . -type d -exec chmod g+s '{}' +

Check the output of shared repository:

git config core.sharedRepository

If the output of last command is empty or doesn’t include group , true or 1, run the following:

git config core.sharedRepository group

Finally, fix the root cause by following the answer from stackoverflow.

Documenting Code ¶

Whenever possible, please add docstrings to your code.

This project follows the google-style docstrings format.

To confirm docstrings are valid, build the docs by running nox -t docs

Good docstrings include information like:

If the intended use-case doesn’t appear clear, what purpose does this function serve? When should someone use it?
What happens during errors/edge-cases.
When dealing with physical values, include units.

Testing ¶

The pytest framework provides unit testing for this project.

Ideally, all new code is paired with new unit tests to exercise that code.

If fixing a bug, consider writing the test first to confirm the existence of the bug, and to confirm that the new code fixes it.

Unit tests should only test a single concise body of code.

Run the full test suite:

nox -t test

Lint using Ruff:

nox -t fix

Typecheck using MyPy:

nox -t type

Build and live-preview documentation:

nox -t preview

Run pre-commit hooks:

nox -t pre-commit

Build the project using PyInstaller:

nox -t build

List the available Nox sessions:

nox --list

Unit tests are located in the tests directory, and are written using the pytest testing framework.

Coding style ¶

In an attempt to keep consistency and maintainability in the code-base, here are some high-level guidelines for code that might not be enforced by linters:

Use f-strings.
Keep/cast path variables as pathlib.Path objects. Don’t use os.path. For public-facing functions, cast path arguments immediately to Path.
Avoid deeply nested code. Techniques like returning early and breaking up a complicated function into smaller functions results in easier-to-read and test code.
Consider if you are double-name-spacing and how modules are meant to be imported. for example, it might be better to name a function read instead of image_read in the module my_package/image.py. Consider the module name-space and check if it’s flattened in __init__.py.

Commit Messages ¶

Use clear, descriptive commit messages.

Format:

type(scope): short description

Examples:

feat(ui): add mission filter dropdown
fix(api): handle timeout exception
docs: clarify setup instructions

Pull Requests ¶

Open a pull request and target the test branch to submit changes to this project.

Don’t target the main branch, as it’s reserved for releases.

Your pull request needs to meet the following guidelines for acceptance:

The Nox test suite must pass without errors and warnings.
Include unit tests. This project maintains high code coverage.
If your changes add capability, update the documentation accordingly.

Feel free to submit early, iteration and improvement can happen as needed.

It’s recommended to open an issue before starting work on anything. This will allow a chance to discuss your approach with the owners and confirm it fits the project’s direction.

Versioning and Release Process ¶

The flow of the versioning and release process is as follows:

All changes are made in the test branch.
When a feature or bug-fix is complete, a pull request is opened to merge into dev branch. This will trigger a draft release (if not already created), Bump the version number and update the changelog.
When the dev branch is stable and ready for release, a pull request is opened to merge into main branch. This will publish the release.

Amendments ¶

This contributing policy may be updated or replaced at any time without notice. Continued contributions constitute acceptance of the current version.