Welcome to the SunPy newcomers' guide. If you have come across this page, you just might be new to SunPy. We aim to be a comprehensive Python package that allows solar physicists to deep dive in the vast amount of solar data available.
Firstly, we want to thank you for your interest in contributing to SunPy! SunPy is an open project that encourages everyone to contribute in any way possible.
The people who help develop or contribute to SunPy are varied in ability and experience with the vast majority being volunteers who dedicate time each week. We pride ourselves on being a welcoming community and we would love to have you become a part of our community.
Although this document mainly focuses on how to make contributions to SunPy's code and documentation, there are other ways to get involved with the SunPy community.
If you have any questions, comments or just want to say hello, we have online chat on Matrix which requires no registration or a Google Group which you message.
A common misconception (which applies to any package) is that all we really want is some Python code, in fact, we do not require only code contributions! If you do not have the time or the desire to code, we have severals of areas where we can use help.
If you use SunPy and stumble upon a problem, the best way to report it is by opening an issue on our GitHub issue tracker. This way we can help you work around the problem and hopefully fix the problem!
You will need to sign into GitHub to report an issue and if you are not already a member of Github, you will have to join. Joining GitHub will make it easier to report and track issues in the future.
If you do not want to join Github, then another way to report your issue is email the SunPy developers list [email protected].
When reporting an issue, please try to provide a short description of the issue with a small code sample, this way we can attempt to reproduce the error. Also provide any error output generated when you encountered the issue, we can use this information to debug the issue. For a good example of how to do this see issue #2879.
If there is functionality that is not currently available in SunPy you can make a feature request. Please write as much information as possible regarding the feature you would like to see in SunPy.
When you go to open either an issue or a feature request, there is a GitHub template that will guide you on the type of information we are seeking. Please be sure to read over the comments in the GitHub text box.
SunPy has online documentation and we try to make sure its as comprehensive as possible. This documentation contains the API of SunPy but also a user guide, an example gallery and developer documents.
However, documentation for any project is a living document. It is never complete and there are always areas that could be expanded upon or could do with proof reading to check if the text is easy to follow and understandable. If parts are confusing or difficult to follow, we would love suggestions or improvements!
We at any one time have a variety of pull requests open and getting reviews is important. Generally the more people that can look over a pull request the better it will turn out and we encourage everyone to do so.
If you would prefer to code instead, the best way to start is to work on an exisiting and known issues. We have several repositories you can investigate. The main one is the SunPy repository with where all the known issues with SunPy are detailed. Each issue should have a series of labels that provide information about the nature of the issue. If you find an issue you'd like to work on, please make sure to add a comment to let people know that you are working on it! This will make it less likely that effort is duplicated.
If you are unsure where to start we suggest the Package Novice label. These are issues that have been deemed a good way to be eased into SunPy and are achievable with little understanding of the SunPy codebase. Please be aware that this does not mean the issue is "easy", just that you do not need to be aware of the underlying structure of SunPy.
We also tag issues for specific events such as Hacktoberfest under the Hacktoberfest label. The scope of the issues should be appropriate for that specific event. We do particpate in several other events but right now we do not have dedicated labels. So please use the above labels for starting issues!
In addition, we have several other repositories that have open issues and you might find these more interesting than the main repository.
Python:
CSS/HTML:
If you already have code that you've developed or already have your own idea of code you'd like to work on please first have a look at the issue list to see if any existing issues are related to your idea. If you find nothing then create your own issue to stimulate the addition of your code and make sure to let people know about it chat room or by email. Creating an issue creates a permanent record. It may be possible your idea may be outside of the scope of the repository you are trying to contribute to and the issue comments are a great place to have that discussion where potential future contributors can also see.
The instructions in this following section are based upon three resources:
We strongly recommend that you read these links.
These links are more in-depth than this guide but you will need to replace astropy with sunpy.
In order to start coding you will need a local Python environment and we would recommend using Anaconda or miniconda (shortened to conda from here on). This method will bypass your operating system Python packages and makes the entire process easier.
The first step is to install the version of conda that corresponds to your operating system and instructions are here. Next we will want to setup the conda environment and we will need to add the conda-forge_ channel as a prerequisite:
$ conda config --add channels conda-forge
$ conda create -n sunpy-dev sunpy
$ source activate sunpy-devThis will create a new conda environment called "sunpy-dev" and install the latest version of SunPy from the conda-forge channel. The next step is remove the conda version of SunPy and install the development version of SunPy. This will require that git be installed.
If you have a GitHub account, we suggest that you fork the SunPy repository (the fork button is to the top right) and use that url for the clone step below. This will make submitting changes easier in the long term for you:
Warning
Do not clone the sunpy repository into $HOME/sunpy. Depending on the operating system this location is used to store downloaded data files.
This will cause conflicts later on, so the last argument (sunpy-git) on the git clone line will become the local folder name of the cloned repository.
$ conda remove sunpy
$ git clone https://github.com/sunpy/sunpy.git sunpy-git
$ cd sunpy-git
$ pip install --no-use-pep517 -e .[all, dev]Now you have the latest version of SunPy installed and are ready to work on it using your favorite editor! Ideally, when you start making changes you want to create a git branch:
$ git checkout -b my_fixYou can change my_fix to anything you prefer.
If you get stuck or want help, just ask here!
Warning
This is a common issue, so please be aware of this.
Within SunPy is a folder called astropy_helpers and this is a git submodule. It is very common issue that this not setup correctly and gets added to your commits.
So we recommend that you always run this at the start:
$ git submodule update --initThis should resolve any differences in the astropy_helpers folder on your machine. If you use:
$ git status
you should hopefully see no changes for the astropy_helpers folder.
Now that you have written some code to address an issue. You will need to check two things:
- The changes you have made are correct, i.e., it fixes a bug or the feature works. This requires you to run the code either manually or by writting/running a test function. pytest is the framework we use for this.
- The changes you have made follow the correct coding style. We follow the PEP8 style for all Python code and depending on your setup, you can use a linter program to check your code. For documentation, we follow the numpydoc style.
We provide more more detail about our :ref: test suite and how to write tests <testing>, and how to :ref: create and style documentation <docs_guidelines>.
Once you have some changes you would like to submit, you will need to commit the changes. This is a three stage process:
- Use
git statusto see that the only changes locally are the right ones. - Use
git add <path to file>to add the changes to git. - Use
git commit -m <message>to label those changes. - Use
git pushto update your fork (copy) of SunPy on GitHub.
Here you replace <message> with some text of the work you have done.
We strongly recommend having a good commit message and this commit guide is worth reading.
Next step is to open a pull request on GitHub. If you are new to pull requests, here is the GitHub guide that is a detailed walkthrough. Go to the "pull requests" tab on your fork and pressing the large green "New pull request" button. Now on the right side from the box marked "compare" you can select your branch. Do one final check to make sure the code changes look correct and then press the green "Create pull request" button.
When you open your pull request, we have a GitHub template that will guide you on what to write in the message box. Please fill this in and title the pull request. Now the final step is to press the green "Create pull request" button.
As soon as you do this, you will be greeted by a message from the "sunpy bot" as well as several continuous integration checks. These are explained on our :ref: Pull Request Review <pr_review> page. But what is important to know is that these run a series of tests to make sure that the changes do not cause any new errors. We strongly recommend that any code changes you have had, follow the PEP8 style and that you have ran the code locally to make sure any changes do not break any existing code. We provide an overview on how to run the test suite :ref: here <testing>. Now we (the SunPy community) can review the code and offer suggestions and once we are happy, we can merge in the pull request.
If you do not have time to finish what you started on or ran out of time during a sprint and do not want to submit a pull request, you can create a git patch instead:
$ git format-patch master --stdout > my_fix.patchYou can rename my_fix to something more relevant.
This way, you still get acknowledged for the work you have achieved.
Now you can email this patch to either the Google Group or a SunPy contributor.
Just remember, if you have any problems get in touch!