What the development guide for your Python package should contain (original) (raw)

Ideally, your package should also have a development guide. This file may live in your package documentation and should be linked to from your CONTRIBUTING.md file (discussed above). A development guide should clearly show technically proficient users how to:

• Set up a development environment locally to work on your package
• Run the test suite
• Build documentation locally

The development guide should also have guidelines for:

• code standards including docstring style, code format and any specific code approaches that the package follows.

It’s also helpful to specify the types of tests you request if a contributor submits a new feature or a change to an existing feature that will not be covered by your existing test suite.

If you have time to document it, it’s also helpful to document your maintainer workflow and release processes.

Why a development guide is important#

It’s valuable to have a development guide, in the case that you wish to:

• Onboard new maintainers.
• Allow technically inclined contributors to make thoughtful and useful code based pull requests to your repository.

It also is important to pyOpenSci that the maintenance workflow is documented in the case that we need to help you onboard new maintainers in the future.

Note

A well thought out continuous integration setup in your repository can allow users to skip building the package locally (especially if they are just updating text).

Tip

A development guide, while strongly recommended, is not a file that pyOpenSci requires a package to have in order to be eligible for review. Some maintainers may also opt to include the development information in their contributing guide.