Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
198 lines (151 loc) · 8.99 KB

CONTRIBUTING.md

File metadata and controls

198 lines (151 loc) · 8.99 KB

Contributing to the JWST Calibration Pipeline

jwst is an open source package written in Python. The source code is available in the JWST Github repository. 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/concerns. We only ask that all contributors adhere to the Space Telescope Code of Conduct.

Tip

The jwst public API and deprecation policy is at https://jwst.readthedocs.io/en/latest/jwst/user_documentation/more_information.html#api-public-vs-private

Reporting bugs / requesting a new feature

If you have encountered a bug when running the pipeline, or wish to request a new feature, open an issue or contact the JWST Help Desk.

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/jwst
cd jwst/

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

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

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 docs/update_contributing_instructions
  1. 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.

  1. Install jwst to your development environment.
  2. Make your changes using your editor of choice.
  3. 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.
  4. Open a new Pull Request requesting that your changes be merged into the main branch of this repository.
  5. Ensure that your change passes automated testing (see TESTING.md for details).
  6. 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 jwst 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 jwst (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 jwst_dev_env python=3.13
mamba activate jwst_dev_env
pip install -e .
hx .

Breaking down what these lines do:

  1. Create a new empty environment called jwst_dev_env: 
    mamba create -n jwst_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 jwst_dev_env
  3. Install the local package (jwst) 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 jwst and one of its dependencies

If you need to make a change in jwst that requires a simultaneous change to one of its dependencies (stcal, stdatamodels, stpipe, etc.), also install that dependency from your local machine to your development environment. For instance, assuming you've cloned the source code for both jwst and stcal, you can do the following from the jwst/ directory:

cd jwst/
pip install -e .
pip install -e ../stcal

Tip

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

mamba create -n jwst_stcal_dev_env python=3.13
mamba activate jwst_stcal_dev_env

Since we do not use a single repository (sometimes called a "monorepo") for these coupled packages, when making a change like this, you will need to make two pull requests: one in the jwst repository, and one in the dependency's repository. However, unit tests will not automatically pass because the pyproject.toml file in jwst points to the last released version of stcal, which does not incorporate your changes. To resolve this (temporarily, for testing) modify the pyproject.toml files in jwst to point to your branch, to demonstrate that unit tests pass.

# jwst/pyproject.toml
[project]
...
dependencies = [
    ...
    "stcal @ git+https://github.com/YOUR_USERNAME/stcal.git@YOUR_BRANCH",
    ...
]

Warning

REMEMBER TO REVERT THE CHANGES TO pyproject.toml BEFORE YOUR BRANCH IS MERGED INTO main.

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.

PEP8 compliance

The code style for the jwst repository generally conforms to PEP8, enforced using ruff. ruff will automatically pick up the appropriate configuration from .ruff.toml and perform only the checks that are turned on for our repository.

Numpy docstring style

Docstrings in jwst conform to the Numpy style guide, enforced with numpydoc-validation.

Spell checking

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

PEP-compliant type hints

The majority of the jwst repository does not have type hints, and type hints are not required for contributions. If type hints are used, though, their compliance with PEP-484 is enforced with mypy.

Writing and maintaining documentation

See docs/README.md for instructions.