Contributing Quickstart — Astropy v7.2.dev34+g711f929ef (original) (raw)

Creating a development environment#

To make and test code changes and build the documentation locally you will need to create a development environment. If you run into problems at any stage do not hesitate to ask for help.

Set up GitHub and Git#

Astropy is hosted on GitHub, and to contribute, you will need a GitHub account.

We use Git for version control and to allow many people to work together on the project. See the GitHub quickstart instructions for installing and configuring git, as well as the Git Resources page.

If you are new to contributing to projects through forking on GitHub, see theGitHub documentation for contributing to projects.

Install a C compiler if needed#

How to do this will depend on your platform.

Windows

You will need Build Tools for Visual Studio.

Note

You DO NOT need to install Visual Studio. You only need “Build Tools for Visual Studio” found by scrolling down to “All downloads” -> “Tools for Visual Studio” -> “Build Tools for Visual Studio”.

Alternative options include:

MacOS

Install the Developer Tools using xcode-select --install. There is no need to install the full Xcode application and this command will install only the command line tools and developer utilities.

Further details and related information can be found athttps://devguide.python.org/setup/#macos.

Linux

For Linux-based installations, you won’t have to install any additional components.

Create a clone of astropy#

If you have not done so already, you will need your own copy of astropy to build it and/or contribute to the source. Astropy is hosted in the astropy GitHub repository and you need to make a clone.

First, create a GitHub Fork by going to the astropy project pageand hitting the Fork button.

Next, clone your GitHub fork to your machine:

git clone https://github.com/YOUR-USER-NAME/astropy.git cd astropy git remote add upstream https://github.com/astropy/astropy.git git fetch upstream --tags

This creates the directory astropy and connects your repository to the upstream (main project) astropy repository.

You can see the remote repositories as follows:

You will see something like:

origin git@github.com:YOUR-USER-NAME/astropy.git (fetch) origin git@github.com:YOUR-USER-NAME/astropy.git (push) upstream https://github.com/astropy/astropy.git (fetch) upstream https://github.com/astropy/astropy.git (push)

Create an isolated development environment#

A key requirement is to have an isolated Python environment, meaning that it is isolated from both your system Python and any other Python environments you may have for doing other work. This is important because the development environment will often be unstable and possibly broken at times, and you don’t want to break your other work.

There are many good options for doing this, including a number of virtual environment managers (e.g., the Python standard library venvmodule). Users who have a preference for a particular virtual environment manager are encouraged to use it!

For this quickstart guide we use the conda package manager provided by miniforge. This is a popular choice and generally works well, especially for newcomers. It is easy to install and use on all platforms and it makes it easy to install different Python versions which can be useful for testing.

Install miniforge and conda#

If you do not already have conda installed, download and install miniforge. The details depend on your system but the end result is to provide a conda executable that you can use to create and manage isolated Python environments.

Now create and activate an astropy-dev conda environment using the following:

conda create -n astropy-dev python graphviz conda activate astropy-dev

Note the graphviz package is required for building the documentation.

Install the development version of astropy#

Now you can install the development version of astropy into your new environment. This will install the latest version of astropy from your local git repo, along with all the dependencies needed to build and fully test astropy:

python -m pip install --editable '.[dev_all]'

Checking the build

At this point you should be able to import astropy from your locally built version:

python -c 'import astropy; astropy.system_info()'

Next you may want to try running some or all of the astropy unit tests. Running the full test suite can take a few minutes, so you may want to start with a single sub-package (e.g. Astronomical Coordinate Systems (astropy.coordinates)):

run a sub set of the test suite

pytest astropy/coordinates

or the whole suite

pytest

Details on running and writing tests can be found in the Testing Guidelinessection.

Install pre-commit#

This is optional, but highly recommended. Pre-commit is a tool that runs a number of Continuous Integration (CI) checks (e.g. code formatting) on your code before you commit it. If you skip this step then it is likely that one or more of those CI checks will fail when you make a pull request, resulting in lost time (yours and CI resources).

Installation is straightforward. From the root of the astropy repository, run:

Now all of the styling checks will be run each time you commit changes, ensuring that the CI formatting checks for your pull request will pass.

Tip

To learn more about pre-commit, see the Pre-commit section.

Creating and submitting a pull request#

You can contribute bug fixes, new features, and documentation updates by submitting a GitHub pull request (PR). This section will guide you through the process. We encourage you to ask for help if you get stuck. The Astropy community is welcoming and friendly and will help you!

If you are new to the Astropy Project and interested to submit a large patch (e.g., a new big feature or significant refactoring), we encourage you to first discuss your ideas on GitHub to increase the chance of your PR being accepted.

Creating a branch#

Your local main branch should always reflect the current state of astropy repository. First ensure it’s up-to-date with the main astropy repository:

git switch main git pull upstream main --ff-only

Now create a development branch for making your changes. For example:

git switch -c subpackage-bug-fix

This changes your working branch from main to the subpackage-bug-fix branch. Keep any changes in this branch specific to one bug or feature so it is clear what the branch brings to astropy. You can have many feature branches and switch in between them using the git switch command.

Using a descriptive branch name can help you stay organized. For example`io-ascii-commented-header` might be a good name for a branch that fixes the commented header issue #15513 in the io.ascii sub-package.

When you want to update the feature branch with changes in main after you created the branch, check the section onupdating a PR.

Making code or documentation changes#

Now comes the fun part where you use your favorite editor or IDE to make changes to the code or documentation! At a high level this breaks into a few parts:

You can see a summary of the changes you’ve currently made by running:

You can then commit your all your changes to your local repository with an explanatorycommit message:

git add files-that-you-changed ... git commit -m "your commit message goes here"

Important

Never merge changes from upstream/main into your feature branch. If changes in main require changes to our code you must Rebase if necessary.

Pushing your changes#

When you want your changes to appear publicly on your GitHub page, push your forked feature branch’s commits:

git push origin --set-upstream subpackage-bug-fix

Here origin is the default name given to your fork on GitHub.

Now your code is on GitHub, but it is not visible to the Astropy maintainers. For that to happen, a pull request needs to be submitted on GitHub.

The first time you push to a new branch on GitHub, you will see a message like below with a useful link to create a pull request:

remote: Create a pull request for 'subpackage-bug-fix' on GitHub by visiting: remote: https://github.com/YOUR-USER-NAME/astropy/pull/new/subpackage-bug-fix

Making a pull request#

If everything looks good, you are ready to make a pull request (PR). A PR is how code from your local repository becomes available to the GitHub community to review and merged into project to appear the in the next release.

Most of the time you can just follow the link that git provided when you pushed your branch and create the PR. If you don’t have that link (and for a few more details), you can follow the Make a pull request instructions.

Follow the instructions in the PR template and fill it out as completely as possible.

If your PR is still a work in progress then instead of clicking “Create pull request”, click on the small down arrow next to it and select “Create draft pull request”. In addition, if your commits are not ready for CI testing, you should include [ci skip] the last commit message – but note that code formatting checks and documentation building will still be done. Formatting and style errors _should_already have been fixed before committing if you have locallyinstalled pre-commit; but if you have not, you can use the Fixing coding style issues to fix them automatically in the PR.

Once submitted (and marked as ready), this request goes to the astropy maintainers and they will review the PR.

Updating your pull request#

Based on the review you get on your pull request, you will probably need to make some adjustments. You can follow the code committing stepsagain to address any feedback and update your pull request:

git push origin subpackage-bug-fix

Any git push will automatically update your pull request with your branch’s changes and restart the Continuous Integration checks.

Tips for a successful pull request#

If you have made it to this point and submitted a pull request, one of the core maintainers will take a look. To make the process as smooth and efficient as possible, here are some tips: