Skip to content

Contributing

Contributing#

Thank you for your interest in contributing to ISOFIT! If you are just getting started, please review the guidelines below to understand how and where you can best support and contribute to this project. Typical contributions may include:

  • Unit tests
  • Code patches
  • Feature enhancements
  • Documentation improvements
  • Bug reports

If you have ideas for new additions, that's great - please contact the maintainers at the addresses given below, and we can coordinate efforts. Our general policy is to for the maintainers to delegate technical authority to individuals to make changes and additions to specific topics.

Getting Started#

First of all, to get a sense of the project's current status and roadmap, please be sure to spend some time reviewing issues in the issue tracker.

If you have have discovered a new issue or task, then go ahead and create a new issue.

Fork and Create a Branch#

ISOFIT follows the Standard Fork and Pull Request workflow.

When you have chosen an issue to work on, start by forking the repo.

Then, create a branch with a descriptive name. A good branch name starts with the issue number you are working on followed by some descriptive text. For example, if you are working on issue #314 you would run:

$ git checkout -b 314-update-docs-libradtran

Testing#

Tests live in isofit/tests/ and are executed using pytest.

Our development strategy employs continuous integration and unit testing to validate all changes. We appreciate you writing additional tests for new modifications or features. In the interest of validating your code, please also be sure to run realistic examples like this:

$ cd $(isofit path examples)/20171108_Pasadena
$ ./modtran.sh

See Testing for more information.

Debug#

ISOFIT uses ray as the multiprocessing backend; however, this package can be unstable for some systems and difficult to develop with. As such, ISOFIT has a debug mode that can be activated via the ISOFIT_DEBUG environment variable.

This is the only environment variable of ISOFIT and is strictly for enabling the DEBUG features of the code. The flag simply disables the ray package and instead uses an in-house wrapper module to emulate the functions of ray. This enables complete circumvention of ray while supporting ray-like syntax in the codebase.

To enable, set the environment variable ISOFIT_DEBUG to any value before runtime. For example:

$ ISOFIT_DEBUG=1 isofit run ...

A Note About Style#

We use Black and isort to maintain style consistency. These are included via pre-commit and should be installed once ISOFIT is installed. To do so, simply run:

$ pre-commit install

Every commit from here on will auto-apply the above packages. Additionally, upon a PR to the dev branch, Black consistency will be checked. Any PRs failing this check will be rejected by the maintainers until it is passing.

If you must apply Black manually, you must first pip install black and then run black isofit from the root of the repository.

Implement Your Changes and Create a Pull Request#

At this point, you are ready to implement your changes!

As you develop, you should make sure that your branch doesn't veer too far from ISOFIT's dev branch. To do this, switch back to your dev branch and make sure it's up to date with ISOFIT's dev branch:

$ git remote add upstream https://github.com/isofit/isofit.git
$ git checkout dev
$ git pull upstream dev

Then update your feature branch from your local copy of dev, and push it!

$ git checkout 314-update-docs-libradtran
$ git rebase dev
$ git push --set-upstream origin 314-update-docs-libradtran

When you are ready to submit your changes back to the ISOFIT repo, go to GitHub and make a Pull Request.

Keeping your Pull Request Updated#

If a maintainer asks you to "rebase" your PR, they're saying that a lot of code has changed, and that you need to update your branch so it's easier to merge.

Here's the suggested workflow:

$ git checkout 314-update-docs-libradtran
$ git pull --rebase upstream dev
$ git push --force-with-lease 314-update-docs-libradtran

Project Decision Making#

Minor changes follow an expedited acceptance process. These are things like:

  • Bug fixes
  • Unit tests
  • Documentation
  • Consolidation that does not change algorithm results or provide significant new functionality
  • New functionality initiated by maintainers, or over which authority has been delegated in advance by maintainers (e.g. through issue assignment)

Minor change pull requests are accepted once they:

  • Pass unit tests and adhere to project coding conventions
  • Get signoff from at least one maintainer, with no objections from any other maintainer

Accepted minor changes will be released in the next major or minor release version. Hotfixes will be expedited as needed.

Major changes include:

  • New functionality, including examples, data, and algorithm changes, over which authority was not delegated in advance
  • Official releases
  • Project policy updates

These are accepted through consensus of a quorum of maintainers. If you would like to include any new algorithms or examples, we highly recommend that they are supported by peer reviewed scientific research.

Release Steps (for Maintainers)#

Releases should trigger a new PyPi upload, and subsequently a fresh upload to conda-forge. Therefore, the revised steps for versioning are:

  • Submit version number change to setup.cfg in dev
  • Trigger a PR from dev to main
  • Accept the PR
  • Go to https://github.com/isofit/isofit/releases
  • Click "Draft a new release"
  • Enter tag version as "v3.8.0" (depending on latest version), and input release title and description
  • Click "Publish release"

Updating uv.lock (for Maintainers)#

The uv.lock file maintains the pinned versions of every dependency for all supported python versions in order to ensure environment reproducibility. This file should be occasionally updated to retrieve dependency updates.

  1. Create a branch from dev
  2. Execute uv lock --upgrade
  3. Commit the changes to uv.lock
  4. Ensure workflows pass with the new dependency pins
  5. uv by default should auto-sync the local virtual environment to the lock file, but you can also manually ensure it via: uv sync

Additionally:

  • When changing the default recommended python version, use uv python pin <version> and commit the .python-version file and follow the above instructions for updating the lock file as well.
  • If a package needs to added or removed from the toml file, use uv [add|remove] <package>. Commit the toml and follow the above.
  • If changing the requires-python field of the toml file, manually do so then follow the above to ensure all dependencies are compatible.

Contributors#

The github maintainers, responsible for handling pull requests, are:

Name Contact
David R. Thompson david.r.thompson@jpl.nasa.gov
Philip G. Brodrick philip.brodrick@jpl.nasa.gov
Niklas Bohn urs.n.bohn@jpl.nasa.gov
James Montgomery J.Montgomery@jpl.nasa.gov
Evan Greenberg evan.greenberg@jpl.nasa.gov

Thanks to the following regular contributors:

Name Affiliation
Alexey Shiklomanov NASA Goddard
Jay Fahlen NASA JPL
Kevin Wurster Planet
Nimrod Carmon NASA JPL
Regina Eckert NASA JPL
Brent Wilder NASA JPL

The ISOFIT codebase was made possible with support from various sources.

The initial algorithm and code was developed by the NASA Earth Science Division data analysis program “Utilization of Airborne Visible/Infrared Imaging Spectrometer Next Generation Data from an Airborne Campaign in India," program NNH16ZDA001N-AVRSNG, managed by Woody Turner.

Later research and maturation was provided by the Jet Propulsion Laboratory and California Institute of Technology President and Director’s Fund, and the Jet Propulsion Laboratory Research and Technology Development Program.

The project is currently supported by the Open Source Tools, Frameworks, and Libraries Program (NNH20ZDA001N), managed by Dr. Steven Crawford.

Neural network radiative transfer is supported by the NASA Center Innovation Fund managed in conjunction with the Jet Propulsion Laboratory Office of the Chief Scientist and Technologist.

The initial research took place at the Jet Propulsion Laboratory, California Institute of Technology, 4800 Oak Grove Dr., Pasadena, CA 91109 USA.