Draft PR review guidelines

Peer review checklist

PR itself (on GitHub)

• PR has a descriptive and succinct title.
• PR has a brief description of what was changed.
• PR is addressing a change that has already been brought up in an issue. This will ensure that the change you propose is desired by the maintainers, and may provide a chance to discuss implementation details prior to PRing which will save everyone time.
• PR cites any related issues in the PR description and uses closing keywords for any issues that should be closed as a result of the PR.
• PR does not have any extraneous file changes associated with it. One common example of an extraneous change is one that was already made in the target branch, but is showing up as part of this PR under Files changed.
• PR does not have any unresolved merge conflicts.
• If implementing a major new feature or algorithm, a notebook demonstrating the proof of effectiveness is linked in the PR description. Depending on the feature, this kind of validation may take too long to run as a test or in a tutorial notebook.

Style

• Code follows Python variable naming conventions, one description is here. Most variables should be snake_case and classes shoud be defined as UpperCamelCase, for example.
• Code uses descriptive variable names throughout.
• Code has no commented out “junk code.”
• Line lengths are short (recommended <88 chars). This includes docstrings. Note: black tries to shorten line lengths but sometimes it is unable to do so automatically, especially for docstrings.
• New files have the appropriate header (example).

Documentation

• Any new public classes/functions have docstrings.
• Any new public classes/functions have been added to the appropriate .rst file here to be rendered by Sphinx.
• Any major new features (like a new algorithm) are accompanied by a succinct tutorial notebook. Or, if it is agreed upon with the maintainers that this is out of scope for the current PR, a new issue has been created specifying that we need a tutorial notebook for this functionality.
• Any new tutorial notebooks have been added to the appropriate folder here and included in the .rst file here to be rendered by Sphinx.
• Notebooks are cleared, that is, they do not have any run cell output. This is to allow Sphinx to run the notebooks every time the documentation is built which ensures nothing has broken.
• Modifications to the documentation render appropriately in the Netlify build.
• References to parameters in the documentation are wrapped in double backticks (`` on either side of the parameter).
• References to classes/function/documentation outside of this package use intersphinx to automatically link to the relevant documentation pages.

Testing

• New public classes/functions are tested to ensure they achieve the desired output.
• New public classes/functions are tested to ensure proper errors are thrown when invalid inputs are passed.

[bdpedigo]

After we’ve done the big “type hint all the things” PR and have a ton of examples to point to?

This seems the most fair thing to me, personally.

[bdpedigo]

Also added this

“Any major new features (like a new algorithm) are accompanied by a succinct tutorial notebook. Or, if it is agreed upon with the maintainers that this is out of scope for the current PR, a new issue has been created specifying that we need a tutorial notebook for this functionality.”