Contributing to open source projects is a fantastic way to advance one’s coding skills; it’s trying to create something, making mistakes, and learning from those mistakes. That’s how we all improve, and we are happy to help others learn.
Being an open source contributor doesn’t just mean writing code, either. You can help out by writing documentation, tests, or even giving feedback about the project (and yes - that includes giving feedback about the contribution process). Some of these contributions may be the most valuable to the project as a whole, because you’re coming to the project with fresh eyes, you can see the errors and assumptions that seasoned contributors have glossed over.
All bugs, feature requests, and other issues related to
aiapy should be recorded using the GitLab issue tracker.
You can find instructions for how to create an issue here.
All conversation regarding these issues should take place on the issue tracker. When a merge request resolves an issue, the issue will be closed and the appropriate merge request will be referenced. Issues will not be closed without a reason given.
Creating a fork¶
If you would like to contribute to
aiapy, you will first need to setup your development environment.
First create a fork of the main
aiapy repository under your GitLab username.
You can find the instructions for how to do this here.
If you don’t already have an account on GitLab, you’ll need to create one.
You can also sign into GitLab using your GitHub username.
Next, clone your fork of
aiapy to your local machine,
git clone https://gitlab.com/<your_username>/``aiapy``.git
Now add the main
aiapy repository as an upstream repository,
git remote add upstream https://gitlab.com/LMSAL_HUB/aia_hub/``aiapy``.git
You can now keep your fork up to date with main repository by running,
git pull upstream main
If you’re using the Miniconda Python distribution (recommended),
create a new environment for
conda create --name ``aiapy``-dev pip conda activate ``aiapy``-dev
If you’re using an alternate python installation, you can also use virtual environments. Next, install the needed dependencies,
cd aiapy pip install -e .[test,docs]
This includes all of the dependencies for the package as well as
pytest for running tests and
sphinx for building the docs.
To make sure everything is working alright, you can run the tests,
See Testing for more details regarding running the tests.
Making a contribution¶
If you want to add a feature or bugfix to
aiapy, start by first making sure the main branch of your fork is up to date with the main branch of the main repository (see above, this will help to prevent potential file conflicts).
Next, create a new branch and switch to it,
git checkout -b my-new-feature
After you’ve made your changes, commit and push them up to GitLab,
git add changed_file_1.py changed_file_2.py git commit -m "short description of my change" git push origin my-new-feature
Once you see the changes in GitLab, create a merge request against the main
You can find instructions for how to do this here.
Others will likely have comments and suggestions regarding your proposed changes.
You can make these changes using the instructions listed above.
At least one other
aiapy developer must approve your changes before the code can be merged.
Additionally, all automated tests should pass and all conversations should be resolved.
Once these steps are complete, the code can be merged and you can delete your branch
Before committing any changes, you should ensure that the all of the tests pass locally. To run the tests,
This will generate report showing which tests passed and which failed (if any).
--remote-data flag will skip tests that require a network connection.
aiapy uses the pytest framework for discovering and running all of the tests.
Additions to the codebase should be accompanied by appropriate tests such that the test coverage of the entire package does not decrease. You can check the test coverage by running,
pytest --remote-data=any --cov aiapy
Additionally, the test suite, including the documentation build and code style checks can be run with tox.
See the SunPy developer’s guide for more information on running the test suite with
Tests should be added to the directory in the appropriate subpackage, e.g. for
calibrate, the tests should be placed in
Your tests can be added to an existing file or placed in a new file following the naming convention
This organization allows the tests to be automatically discovered by pytest.
There are several tests that require a working installation of sswidl in order to compare results from IDL and Python.
This is managed via the hissw package.
If you’d like to run these tests, you must first tell
hissw where to find your IDL and SSW installations by placing the following lines in the file:
[hissw] ssw_home=/path/to/ssw idl_home=/another/path/to/idl
ssw_home is the path to the top of the sswidl tree and
idl_home is the path to a working installation of IDL.
For more details, see the hissw documentation.
If a working installation is not available, these tests are automatically skipped.
All documentation is written in reStructuredText and rendered using Sphinx. Documentation strings are automatically pulled from all modules, functions and classes to create the API documentation. You can build and test the documentation locally by running,
cd docs make html
This will run Sphinx on the restructured text files in order to create the HTML version of the documentation.
The built documentation, in HTML format, is in
All contributors to the
aiapy codebase should follow the SunPy developer’s guide.
This guide lays out a set of best practices for contributing, reviewing, testing, and documenting code.
All contributions to
aiapy must adhere to the Python in Heliophysics Community Standards.