Skip to content

Contributing

Jump to bottom
David Hoese edited this page May 26, 2023 · 7 revisions

Contributing

DEPRECATED: See https://sift.readthedocs.io/en/latest/index.html

SIFT is an open source project with its core development happening at the Space Science and Engineering Center (SSEC) at the University of Wisconsin - Madison. We welcome all contributions whether they are bug reports, feature requests, bug fixes, new features, or documentation updates.

The sections below will attempt to provide the necessary information for contribution changes to the GitHub repository. Note that some sections below may refer to SSEC-specific resources or may only apply to older versions of SIFT. Please contact the development team if you have any questions.

Development Team

The majority of the SIFT team works at the Space Science and Engineering Center at the University of Wisconsin - Madison. Ray Garcia (@rayg-ssec) and David Hoese (@djhoese) are the core developers on the project and will help with any questions you have as best they can. Other SSEC developers like Eva Schiffer (@evas-ssec) or various undergraduate programming students can also be seen making contributions from time to time. If you'd like to chat with the developers about SIFT programming and design questions you can do so on our Gitter Chat.

SIFT is managed and used in training by Scott Lindstrom (@ScottLindstrom) and Jordan Gerth (@jgerth).

Bug Reporting

If you'd like to file a bug report please click the "Issues" button at the top of the GitHub page and then click the button "New issue" button. It is a good idea to search through the existing issues to make sure the bug you've found or the feature you are requesting hasn't already been filed.

Adding new features

If you have an idea for a feature you'd like to implement in SIFT please create an issue on GitHub to discuss the feature with the core developers. You can also chat with SIFT developers on the Gitter chat. They may be able to help guide you on how to add the feature.

Developer Installation

The following instructions are for software developers or users who want to install the unstable version of SIFT directly from GitHub. The easiest way to do this is to first follow the conda installation instructions by creating a new environment with the stable version of SIFT installed.

Next we will need to uninstall the conda package of SIFT:

conda uninstall --force uwsift

This will force uwsift to be uninstalled without uninstalling its dependencies. We can then install the unstable version of SIFT from its source code. If you don't plan on making modifications to the SIFT source code then we can run the following command and run the uwsift package as usual (see above):

pip install git+https://github.com/ssec/sift.git

If you do plan on making changes to the source code and running SIFT to see the changes, you first need to clone the git repository:

git clone git@github.com:ssec/sift.git

Note the above command uses "SSH" access to GitHub which requires setting up SSH keys on your GitHub account. You can alternatively use the https://github.com/ssec/sift.git URL.

Now we can install SIFT from the source code:

cd sift
pip install -e .

Any changes made to the source code from here on out will take effect immediately.

Building the Developer Documentation

SIFT uses the sphinx documentation tool to generate its developer documentation website. The website is automatically generated from the contents of the master branch on GitHub. If you'd like to make changes to the documentation you can build the website locally to test things. In addition to the above Developer Installation process, you'll need to run the following commands to install sphinx-specific dependencies:

conda install -c conda-forge sphinx sphinx_rtd_theme
pip install blockdiag sphinxcontrib-seqdiag sphinxcontrib-blockdiag

You can then generate the documentation by running:

cd doc
make html

You can then open the build/html/index.html file in your preferred browser to preview the website.

Additional Satpy Readers

Starting with SIFT 1.1 Satpy is used for reading all input data files. By default SIFT limits the available readers to avoid unsupported data formats and other unexpected behavior. To customize the readers used you can specify the UWSIFT_DATA_READING__READERS environment variables (not the last specified has two underscores). You can set it to a list of readers. For example:

export UWSIFT_DATA_READING_READERS = "['abi_l1b', 'ami_l1b']"

Writing Tests

All bug fixes and features contributed to SIFT should have an associated test. Writing tests for an application as complex as SIFT (multithreaded data loading, PyQt GUI framework, OpenGL visualization, etc) can be difficult. We've gathered some of our lessons learned in writing tests for SIFT in the Writing tests for SIFT document.

Developer Workflow

TODO: This section was written before SIFT 1.1. A lot has changed since this was originally written and may be partially incorrect. It will be updated in the future.

  • Fork ssec/sift project on github. Point your working copy at that clone.
    • Suggest using 'upstream' remote to ssec/sift, 'origin' to yourgithubuser/sift.
  • Identify or create an issue describing the work to be done.
  • Create a "feature-XXXXXXXX", "bugfix-XXXXXXXX", "refactor-XXXXXXXX", or "experiment-XXXXXXXX" branch you'll work on. Branch names should indicate in two to four words the nature of the changes in the branch.
  • Write/amend/remove code!
  • Don't make architectural changes without at least giving djhoese and rayg-ssec the opportunity to stub it out or otherwise provide preliminary review.
  • Test your changes locally.
  • Check in your changes and push them to your fork.
    • Preferably using "#__" syntax in your commit messages.
    • Observe OSS best-practices in your git commit messages, with an active summary line followed by details.
  • Submit a pull request (PR), identifying djhoese and/or rayg-ssec as reviewers.
  • Update your changes in response to feedback, including any PEP8 recommendations from stickler CI.
  • Communicate with other devs through Github PR interface, and Gitter.im as needed.
  • See the Testing page for information on sample data and common test cases.

Windows Virtual Machine

If you do not develop on a Windows machine there is a VMWare Virtual Machine available by connecting to cifs://beans/Users$/davidh/Data/Machines/ via Finder's Connect to Server or other CIFS supported mounting solution. Once you open the virtual machine in VMWare you should be able to activate and update the sift package with the following commands:

activate sift
conda update -c http://larch.ssec.wisc.edu/channels/sift sift
Clone this wiki locally