Contributing to NumPy#

Not a coder? Not a problem! NumPy is multi-faceted, and we can use a lot of help.These are all activities we’d like to get help with (they’re all important, sowe list them in alphabetical order):

  • Code maintenance and development

  • Community coordination

  • DevOps

  • Developing educational content & narrative documentation

  • Fundraising

  • Marketing

  • Project management

  • Translating content

  • Website design and development

  • Writing technical documentation

We understand that everyone has a different level of experience,also NumPy is a pretty well-established project, so it’s hard tomake assumptions about an ideal “first-time-contributor”.So, that’s why we don’t mark issues with the “good-first-issue”label. Instead, you’ll findissues labeled “Sprintable”.These issues can either be:

  • Easily fixed when you have guidance from an experiencedcontributor (perfect for working in a sprint).

  • A learning opportunity for those ready to dive deeper,even if you’re not in a sprint.

Additionally, depending on your prior experience, some “Sprintable”issues might be easy, while others could be more challenging for you.

The rest of this document discusses working on the NumPy code base and documentation.We’re in the process of updating our descriptions of other activities and roles.If you are interested in these other activities, please contact us!You can do this viathenumpy-discussion mailing list,or onGitHub (open an issue or comment on arelevant issue). These are our preferred communication channels (open source is openby nature!), however if you prefer to discuss in a more private space first,you can do so on Slack (seenumpy.org/contribute for details).

Development process - summary#

Here’s the short summary, complete TOC links are below:

  1. If you are a first-time contributor:

    • Go tonumpy/numpy and click the“fork” button to create your own copy of the project.

    • Clone the project to your local computer:

      gitclone--recurse-submoduleshttps://github.com/your-username/numpy.git

    • Change the directory:

      cdnumpy

    • Add the upstream repository:

      gitremoteaddupstreamhttps://github.com/numpy/numpy.git

    • Now,gitremote-v will show two remote repositories named:

      • upstream, which refers to thenumpy repository

      • origin, which refers to your personal fork

    • Pull the latest changes from upstream, including tags:

      gitcheckoutmaingitpullupstreammain--tags

    • Initialize numpy’s submodules:

      gitsubmoduleupdate--init

  2. Develop your contribution:

    • Create a branch for the feature you want to work on. Since thebranch name will appear in the merge message, use a sensible namesuch as ‘linspace-speedups’:

      gitcheckout-blinspace-speedups

    • Commit locally as you progress (gitadd andgitcommit)Use aproperly formatted commit message,write tests that fail before your change and pass afterward, run all thetests locally. Be sure to document anychanged behavior in docstrings, keeping to the NumPy docstringstandard.

  3. To submit your contribution:

    • Push your changes back to your fork on GitHub:

      gitpushoriginlinspace-speedups

    • Go to GitHub. The new branch will show up with a green Pull Requestbutton. Make sure the title and message are clear, concise, and self-explanatory. Then click the button to submit it.

    • If your commit introduces a new feature or changes functionality, post onthemailing list to explain your changes. For bug fixes, documentationupdates, etc., this is generally not necessary, though if you do not getany reaction, do feel free to ask for review.

  4. Review process:

    • Reviewers (the other developers and interested community members) willwrite inline and/or general comments on your Pull Request (PR) to helpyou improve its implementation, documentation and style. Every singledeveloper working on the project has their code reviewed, and we’ve cometo see it as friendly conversation from which we all learn and theoverall code quality benefits. Therefore, please don’t let the reviewdiscourage you from contributing: its only aim is to improve the qualityof project, not to criticize (we are, after all, very grateful for thetime you’re donating!). See ourReviewer Guidelines for more information.

    • To update your PR, make your changes on your local repository, commit,run tests, and only if they succeed push to your fork. As soon asthose changes are pushed up (to the same branch as before) the PR willupdate automatically. If you have no idea how to fix the test failures,you may push your changes anyway and ask for help in a PR comment.

    • Various continuous integration (CI) services are triggered after each PRupdate to build the code, run unit tests, measure code coverage and checkcoding style of your branch. The CI tests must pass before your PR can bemerged. If CI fails, you can find out why by clicking on the “failed”icon (red cross) and inspecting the build and test log. To avoid overuseand waste of this resource,test your work locally beforecommitting.

    • A PR must beapproved by at least one core team member before merging.Approval means the core team member has carefully reviewed the changes,and the PR is ready for merging.

  5. Document changes

    Beyond changes to a functions docstring and possible description in thegeneral documentation, if your change introduces any user-facingmodifications they may need to be mentioned in the release notes.To add your change to the release notes, you need to create a short filewith a summary and place it indoc/release/upcoming_changes.The filedoc/release/upcoming_changes/README.rst details the format andfilename conventions.

    If your change introduces a deprecation, make sure to discuss this first onGitHub or the mailing list first. If agreement on the deprecation isreached, followNEP 23 deprecation policy to add the deprecation.

  6. Cross referencing issues

    If the PR relates to any issues, you can add the textxrefgh-xxxx wherexxxx is the number of the issue to github comments. Likewise, if the PRsolves an issue, replace thexref withcloses,fixes or any ofthe other flavorsgithub accepts.

    In the source code, be sure to preface any issue or PR reference withgh-xxxx.

For a more detailed discussion, read on and follow the links at the bottom ofthis page.

Guidelines#

  • All code should have tests (seetest coverage below for more details).

  • All code should bedocumented.

  • No changes are ever committed without review and approval by a coreteam member. Please ask politely on the PR or on themailing list if youget no response to your pull request within a week.

Stylistic guidelines#

  • Set up your editor to followPEP 8 (remove trailing white space, no tabs, etc.). Check codewith ruff.

  • Use NumPy data types instead of strings (np.uint8 instead of"uint8").

  • Use the following import conventions:

    importnumpyasnp

  • For C code, seeNEP 45.

Test coverage#

Pull requests (PRs) that modify code should either have new tests, or modify existingtests to fail before the PR and pass afterwards. You shouldrun the tests before pushing a PR.

Running NumPy’s test suite locally requires some additional packages, such aspytest andhypothesis. The additional testing dependencies are listedinrequirements/test_requirements.txt in the top-level directory, and canconveniently be installed with:

$ python -m pip install -r requirements/test_requirements.txt

Tests for a module should ideally cover all code in that module,i.e., statement coverage should be at 100%.

To measure the test coverage, run:

$ spin test --coverage

This will create a report inhtml format atbuild/coverage, which can beviewed with your browser, e.g.:

$ firefox build/coverage/index.html

Building docs#

To build the HTML documentation, use:

spindocs

You can also runmake from thedoc directory.makehelp listsall targets.

To get the appropriate dependencies and other requirements,seeBuilding the NumPy API and reference docs.

Development process - details#

The rest of the story

NumPy-specific workflow is innumpy-development-workflow.