Skip to content

Pull Requests

The majority of our rules regarding PRs are documented and enforced by the GitHub config and templates. These notes complement those.

Opening a PR

Try to keep a PR's scope small and focused. It's a good practice to stick to the scope shown by the conventional commit type.

It's strongly encouraged to open a separate PR:

  • For bugfixes.
  • If putting everything in 1 PR would make it too big.
  • If another wip feature might benefit from merging a part of your change.

It's encouraged to open a separate PR for:

  • preparatory refactorings
  • anything that can be reviewed separately without knowledge of the whole context

Mention in a comment:

  • any out of scope functionality or improvement
  • related PRs (e.g. in a plugin repo)

Reviewing a PR

The reviewer should give a first feedback:

  • by the end of the day if the review was requested before lunch time
  • by lunch time next day if the review was requested after lunch time

An ideal review is approved, possibly with comments. Then the author can resolve all of the comments and merge without needing to re-request a review. Both the author and reviewer should aim for this.

After giving a first feedback, monitor the PR for questions, discussions etc. Especially if its status is "Changes requested."

Format

  • Prefer comments next to the related piece of code over general remarks.
  • Tutorials, "how does it work?" explanations in a review are discouraged. Link to external sources instead.
  • Try to stick to 1 improvement / comment. This way, it's easier to decide whether a conversation can be resolved.
  • Distinguish between must-have and nice-to-have. Especially if you're suggesting lots of improvements. :-)

Content

Some things to look out for in a review:

  • further test cases
  • necessary explanations / documentation
  • already existing similar functionality

It's encouraged to suggest "semi-related" changes and improvements. In such cases, mention explicitly that these are optional for the current PR. Some examples:

  • refactorings that can be implemented in a follow-up PR
  • bugs in already existing functionality that were revealed by the current PR
  • improvements for already existing functionality

Configuring Slack Notifications

  • User /github subscribe sourcery-ai reviews in a channel or with the GitHub bot directly
  • To set reminders for reviews, and receive updates on information relevant to you go to https://github.com/settings/reminders. Here's an example configuration: GitHub Slack Notifications