{ "__type": "IngestedDoc", "__tag": 4010, "_content": {}, "_ordered_sections": [], "item_file": null, "item_line": null, "item_type": null, "aliases": [], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "see_also": [], "signature": null, "references": null, "qa": "dev:index", "arbitrary": [ { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "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, so we list them in alphabetical order):" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Code maintenance and development" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Community coordination" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "DevOps" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Developing educational content & narrative documentation" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Fundraising" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Marketing" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Project management" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Translating content" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Website design and development" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Writing technical documentation" } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "We understand that everyone has a different level of experience, also NumPy is a pretty well-established project, so it's hard to make 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 find " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "issues labeled \"Sprintable\"" } ], "url": "https://github.com/numpy/numpy/labels/sprintable", "title": "" }, { "__type": "Text", "__tag": 4046, "value": ". These issues can either be:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "Easily fixed" } ] }, { "__type": "Text", "__tag": 4046, "value": " when you have guidance from an experienced contributor (perfect for working in a sprint)." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "A learning opportunity" } ] }, { "__type": "Text", "__tag": 4046, "value": " for those ready to dive deeper, even if you're not in a sprint." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Additionally, depending on your prior experience, some \"Sprintable\" issues might be easy, while others could be more challenging for you." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "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 via the " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "numpy-discussion mailing list" } ], "url": "https://mail.python.org/mailman/listinfo/numpy-discussion", "title": "" }, { "__type": "Text", "__tag": 4046, "value": ", or on " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "GitHub" } ], "url": "https://github.com/numpy/numpy", "title": "" }, { "__type": "Text", "__tag": 4046, "value": " (open an issue or comment on a relevant issue). These are our preferred communication channels (open source is open by nature!), however if you prefer to discuss in a more private space first, you can do so on Slack (see " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "numpy.org/contribute" } ], "url": "https://numpy.org/contribute/", "title": "" }, { "__type": "Text", "__tag": 4046, "value": " for details)." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Contributing to NumPy" } ], "level": 0, "target": "devindex" }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Here's the short summary, complete TOC links are below:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": true, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If you are a first-time contributor:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Go to " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "https://github.com/numpy/numpy" } ], "url": "https://github.com/numpy/numpy", "title": "" }, { "__type": "Text", "__tag": 4046, "value": " and click the \"fork\" button to create your own copy of the project." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Clone the project to your local computer " } ] }, { "__type": "Code", "__tag": 4050, "value": "git clone --recurse-submodules https://github.com/your-username/numpy.git", "execution_status": null } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Change the directory " } ] }, { "__type": "Code", "__tag": 4050, "value": "cd numpy", "execution_status": null } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Add the upstream repository " } ] }, { "__type": "Code", "__tag": 4050, "value": "git remote add upstream https://github.com/numpy/numpy.git", "execution_status": null } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Now, " }, { "__type": "InlineCode", "__tag": 4051, "value": "git remote -v" }, { "__type": "Text", "__tag": 4046, "value": " will show two remote repositories named:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "upstream" }, { "__type": "Text", "__tag": 4046, "value": ", which refers to the " }, { "__type": "InlineCode", "__tag": 4051, "value": "numpy" }, { "__type": "Text", "__tag": 4046, "value": " repository" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "origin" }, { "__type": "Text", "__tag": 4046, "value": ", which refers to your personal fork" } ] } ] } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Pull the latest changes from upstream, including tags " } ] }, { "__type": "Code", "__tag": 4050, "value": "git checkout main\ngit pull upstream main --tags", "execution_status": null } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Initialize numpy's submodules " } ] }, { "__type": "Code", "__tag": 4050, "value": "git submodule update --init", "execution_status": null } ] } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Develop your contribution:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Create a branch for the feature you want to work on. Since the branch name will appear in the merge message, use a sensible name such as 'linspace-speedups' " } ] }, { "__type": "Code", "__tag": 4050, "value": "git checkout -b linspace-speedups", "execution_status": null } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Commit locally as you progress (" }, { "__type": "InlineCode", "__tag": 4051, "value": "git add" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "git commit" }, { "__type": "Text", "__tag": 4046, "value": ") Use a " }, { "__type": "InlineRole", "__tag": 4003, "value": "properly formatted", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " commit message, write tests that fail before your change and pass afterward, run all the " }, { "__type": "InlineRole", "__tag": 4003, "value": "tests locally", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ". Be sure to document any changed behavior in docstrings, keeping to the NumPy docstring " }, { "__type": "InlineRole", "__tag": 4003, "value": "standard", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "To submit your contribution:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Push your changes back to your fork on GitHub " } ] }, { "__type": "Code", "__tag": 4050, "value": "git push origin linspace-speedups", "execution_status": null } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Go to GitHub. The new branch will show up with a green Pull Request button. Make sure the title and message are clear, concise, and self- explanatory. Then click the button to submit it." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If your commit introduces a new feature or changes functionality, post on the " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "mailing list" } ], "url": "https://mail.python.org/mailman/listinfo/numpy-discussion", "title": "" }, { "__type": "Text", "__tag": 4046, "value": " to explain your changes. For bug fixes, documentation updates, etc., this is generally not necessary, though if you do not get any reaction, do feel free to ask for review." } ] } ] } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Review process:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Reviewers (the other developers and interested community members) will write inline and/or general comments on your Pull Request (PR) to help you improve its implementation, documentation and style. Every single developer working on the project has their code reviewed, and we've come to see it as friendly conversation from which we all learn and the overall code quality benefits. Therefore, please don't let the review discourage you from contributing: its only aim is to improve the quality of project, not to criticize (we are, after all, very grateful for the time you're donating!). See our " }, { "__type": "CrossRef", "__tag": 4002, "value": "Reviewer Guidelines", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "dev:reviewer_guidelines" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": " for more information." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "To update your PR, make your changes on your local repository, commit, " }, { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "run tests, and only if they succeed" } ] }, { "__type": "Text", "__tag": 4046, "value": " push to your fork. As soon as those changes are pushed up (to the same branch as before) the PR will update 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." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Various continuous integration (CI) services are triggered after each PR update to build the code, run unit tests, measure code coverage and check coding style of your branch. The CI tests must pass before your PR can be merged. 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 overuse and waste of this resource, " }, { "__type": "InlineRole", "__tag": 4003, "value": "test your work", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " locally before committing." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A PR must be " }, { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "approved" } ] }, { "__type": "Text", "__tag": 4046, "value": " 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." } ] } ] } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Document changes" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Beyond changes to a functions docstring and possible description in the general documentation, if your change introduces any user-facing modifications they may need to be mentioned in the release notes. To add your change to the release notes, you need to create a short file with a summary and place it in " }, { "__type": "InlineCode", "__tag": 4051, "value": "doc/release/upcoming_changes" }, { "__type": "Text", "__tag": 4046, "value": ". The file " }, { "__type": "InlineCode", "__tag": 4051, "value": "doc/release/upcoming_changes/README.rst" }, { "__type": "Text", "__tag": 4046, "value": " details the format and filename conventions." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If your change introduces a deprecation, make sure to discuss this first on GitHub or the mailing list first. If agreement on the deprecation is reached, follow " }, { "__type": "InlineRole", "__tag": 4003, "value": "NEP 23 deprecation policy ", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " to add the deprecation." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Cross referencing issues" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If the PR relates to any issues, you can add the text " }, { "__type": "InlineCode", "__tag": 4051, "value": "xref gh-xxxx" }, { "__type": "Text", "__tag": 4046, "value": " where " }, { "__type": "InlineCode", "__tag": 4051, "value": "xxxx" }, { "__type": "Text", "__tag": 4046, "value": " is the number of the issue to github comments. Likewise, if the PR solves an issue, replace the " }, { "__type": "InlineCode", "__tag": 4051, "value": "xref" }, { "__type": "Text", "__tag": 4046, "value": " with " }, { "__type": "InlineCode", "__tag": 4051, "value": "closes" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "fixes" }, { "__type": "Text", "__tag": 4046, "value": " or any of the other flavors " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "github accepts" } ], "url": "https://help.github.com/en/articles/closing-issues-using-keywords", "title": "" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In the source code, be sure to preface any issue or PR reference with " }, { "__type": "InlineCode", "__tag": 4051, "value": "gh-xxxx" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For a more detailed discussion, read on and follow the links at the bottom of this page." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Development process - summary" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "All code should have tests (see " }, { "__type": "InlineRole", "__tag": 4003, "value": "test coverage", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " below for more details)." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "All code should be " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "documented" } ], "url": "https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard", "title": "" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "No changes are ever committed without review and approval by a core team member. Please ask politely on the PR or on the " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "mailing list" } ], "url": "https://mail.python.org/mailman/listinfo/numpy-discussion", "title": "" }, { "__type": "Text", "__tag": 4046, "value": " if you get no response to your pull request within a week." } ] } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Guidelines" } ], "level": 2, "target": "guidelines" }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Set up your editor to follow " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "PEP 8" } ], "url": "https://www.python.org/dev/peps/pep-0008/", "title": "" }, { "__type": "Text", "__tag": 4046, "value": " (remove trailing white space, no tabs, etc.). Check code with ruff." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Use NumPy data types instead of strings (" }, { "__type": "InlineCode", "__tag": 4051, "value": "np.uint8" }, { "__type": "Text", "__tag": 4046, "value": " instead of " }, { "__type": "InlineCode", "__tag": 4051, "value": "\"uint8\"" }, { "__type": "Text", "__tag": 4046, "value": ")." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Use the following import conventions " } ] }, { "__type": "Code", "__tag": 4050, "value": "import numpy as np", "execution_status": null } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For C code, see " }, { "__type": "InlineRole", "__tag": 4003, "value": "NEP 45 ", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Stylistic guidelines" } ], "level": 2, "target": "stylistic-guidelines" }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Pull requests (PRs) that modify code should either have new tests, or modify existing tests to fail before the PR and pass afterwards. You should " }, { "__type": "CrossRef", "__tag": 4002, "value": "run the tests", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "dev:development_environment" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": " before pushing a PR." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Running NumPy's test suite locally requires some additional packages, such as " }, { "__type": "InlineCode", "__tag": 4051, "value": "pytest" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "hypothesis" }, { "__type": "Text", "__tag": 4046, "value": ". The additional testing dependencies are listed in " }, { "__type": "InlineCode", "__tag": 4051, "value": "requirements/test_requirements.txt" }, { "__type": "Text", "__tag": 4046, "value": " in the top-level directory, and can conveniently be installed with " } ] }, { "__type": "Code", "__tag": 4050, "value": "$ python -m pip install -r requirements/test_requirements.txt", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Tests for a module should ideally cover all code in that module, i.e., statement coverage should be at 100%." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "To measure the test coverage, run " } ] }, { "__type": "Code", "__tag": 4050, "value": "$ spin test --coverage", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This will create a report in " }, { "__type": "InlineCode", "__tag": 4051, "value": "html" }, { "__type": "Text", "__tag": 4046, "value": " format at " }, { "__type": "InlineCode", "__tag": 4051, "value": "build/coverage" }, { "__type": "Text", "__tag": 4046, "value": ", which can be viewed with your browser, e.g. " } ] }, { "__type": "Code", "__tag": 4050, "value": "$ firefox build/coverage/index.html", "execution_status": null } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Test coverage" } ], "level": 2, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "To build the HTML documentation, use " } ] }, { "__type": "Code", "__tag": 4050, "value": "spin docs", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "You can also run " }, { "__type": "InlineCode", "__tag": 4051, "value": "make" }, { "__type": "Text", "__tag": 4046, "value": " from the " }, { "__type": "InlineCode", "__tag": 4051, "value": "doc" }, { "__type": "Text", "__tag": 4046, "value": " directory. " }, { "__type": "InlineCode", "__tag": 4051, "value": "make help" }, { "__type": "Text", "__tag": 4046, "value": " lists all targets." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "To get the appropriate dependencies and other requirements, see " }, { "__type": "CrossRef", "__tag": 4002, "value": "howto-build-docs", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "dev:howto_build_docs" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Building docs" } ], "level": 2, "target": "building-docs" }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The rest of the story" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "Setting up and using your development environment", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "dev:development_environment" }, "kind": "exists" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "Building the NumPy API and reference docs", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "dev:howto_build_docs" }, "kind": "exists" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "Development workflow", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "dev:development_workflow" }, "kind": "exists" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "Advanced debugging tools", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "dev:development_advanced_debugging" }, "kind": "exists" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "Using GitHub Codespaces for NumPy development", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "dev:development_ghcodespaces" }, "kind": "exists" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "Reviewer guidelines", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "dev:reviewer_guidelines" }, "kind": "exists" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "NumPy C style guide", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "dev:https::numpy.org:neps:nep-0045-c_style_guide.html" }, "kind": "exists" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "For downstream package authors", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "dev:depending_on_numpy" }, "kind": "exists" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "Releasing a version", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "dev:releasing" }, "kind": "exists" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "NumPy governance", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "dev:governance:index" }, "kind": "exists" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "How to contribute to the NumPy documentation", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "dev:howto-docs" }, "kind": "exists" } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "NumPy-specific workflow is in " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy-development-workflow", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "dev:development_workflow" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Target", "__tag": 4061, "label": "mailing list" } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Development process - details" } ], "level": 1, "target": null } ], "local_refs": [] }