CONTRIBUTING.md

Contributing to sphersgeo

sphersgeo is an open source package written in Rust. Python classes are defined with pyo3 in src/lib.rs, and a Python wheel built with maturin.

The source code is available at https://github.com/spacetelescope/sphersgeo. New contributions and contributors are very welcome! Do not hesitate to reach out to the package maintainers if you are new to open-source development or if you have any questions or concerns. We only ask that all contributors adhere to the Space Telescope Code of Conduct.

Reporting bugs / requesting a new feature

If you have encountered a bug, or wish to request a new feature, open an issue.

Suggesting code changes / contributions

Tip

If you are new to GitHub, to git, or to version-control systems in general, refer to the GitHub tutorial and / or to the git reference manual.

To suggest a specific code change, or to contribute new code:

1. Fork this repository.

2. Clone your fork to your local machine:

   git clone https://github.com/YOUR_USERNAME/sphersgeo
   cd sphersgeo/

3. Add the upstream repository, as a remote, to your local clone:

   git remote add upstream https://github.com/spacetelescope/sphersgeo

Tip

When making changes, create a new "branch" for each new feature or bug fix. We recommend naming your new branch something like feature/cool_new_feature, fix/thing_that_was_fixed, docs/updated_description_of_feature, etc:

git fetch upstream --tags
git checkout upstream/main -b fix/that_annoying_bug

4. Install pre-commit to automatically check your changes for formatting issues:

   pip install pre-commit
   pre-commit install

Tip

To run pre-commit checks manually, do pre-commit run --all.

5. Install sphersgeo to your development environment.
6. Make your changes using your editor of choice.
7. Commit and push your changes to your fork as a new branch:

   git add changed_file.py
   git commit -m "description of changes"
   git push

   The git reference manual has details on what these commands do.
8. Open a new Pull Request requesting that your changes be merged into the main branch of this repository.
9. Ensure that your change passes automated testing.
10. Complete the items in the Tasks checklist (created when you open the pull request) to the best of your ability.

Once your pull request is created, it will need to be reviewed and approved by the code maintainer team. They may require changes from you before your code can be merged, in which case go back and make those changes, run tests again, and push the changes to the branch you made earlier.

Keeping your development branch current with main

As sphersgeo is constantly evolving, you will often encounter the situation where you've made changes to your branch, but in that time there are new commits on upstream/main from other developers. Incorporate those changes into your branch, either automatically with the button on the GitHub pull request webpage, or manually with git rebase.

Incorporate upstream changes automatically with button on GitHub pull request page

Usually, GitHub can rebase a branch automatically. If you see "This branch is out-of-date with the base branch", you will have the option to "Update with merge commit" or "Update with rebase". Updating with a merge commit is usually safer.

However, if the changes to main touch the same lines as your changes, you will see "This branch has conflicts that must be resolved". You will need to manually resolve these conflicts yourself; follow the steps described on the page.

Incorporate upstream changes manually with git rebase

Rebase your current branch onto upstream/main to apply any new changes on top of yours:

git fetch --all
git rebase -i upstream/main

For more information on how to use git rebase, see the git rebase documentation or Atlassian's tutorial on rebasing.

Once you've completed your rebase, you will need to "force push" your branch to overwrite your branch on GitHub:

git push -u origin -f feature/cool_new_feature

Creating a development environment

When developing sphersgeo (or any other Python package), you should install the package locally to a development environment.

Tip

Python "environments" are isolated Python installations, confined to a single directory, where you can install packages, dependencies, and tools without cluttering your system Python libraries.

You can create a development environment with mamba / conda:

mamba create -n sphersgeo_dev_env python=3.13
mamba activate sphersgeo_dev_env
pip install -e .
hx .

Breaking down what these lines do:

1. Create a new empty environment called sphersgeo_dev_env:

   mamba create -n sphersgeo_dev_env python=3.13

2. "Activate" the environment (change shell variables in the current session to point to the isolated Python installation):

   mamba activate sphersgeo_dev_env

3. Install the local package (sphersgeo) to your environment in "editable mode", so that any code changes will be instantly reflected in the installed package (useful for testing):

   pip install -e .

4. Run your editor of choice (in this example I use Helix hx):

   hx .

Making simultaneous changes to sphersgeo and one of its dependencies

If you need to make a change in sphersgeo that requires a simultaneous change to one of its dependencies, also install that dependency from your local machine to your development environment.

Tip

It might be easier to use a separate Python environment (mamba / conda, virtualenv, uv, etc.) for this work.

Code style

We use pre-commit to enforce uniform code style and standards.

pip install pre-commit
pre-commit run

You can also install pre-commit locally, to run checks before every git commit action:

pre-commit install

The full configuration for pre-commit checks can be found in .pre-commit-config.yaml.

Spell checking

We use Codespell to check for common misspellings in both our codebase and documentation.