Do you include a useful description of your changes?

Last updated by Brook Jeynes [SSW] 6 months ago.See history

This rule has been archived

When creating a Pull Request with your changes, it is important to have a good description that will help the reviewer to understand what was done.

Leaving the description blank is common and not helpful. There are also cases where people overexplain. You should try to include just the right amount of information.

PR title: Update Rule “meaningful-pbi-titles/rule”

PR description:

Figure: Bad example - Cannot tell what was done here

::: greybox PR title: Update Rule “meaningful-pbi-titles/rule”

PR description: Changes made:

  1. Added missing video figure to embedded YouTube video
  2. Fixed typo:
    From:
    Use emojis. See our rule on emojis in Scrum).
    To:
    Use emojis. See our rule on emojis in Scrum ::: ::: ok Figure: OK example - What was done is clear, but both editor and reviewer may spend too much time on the description of such simple changes :::

Try to make generic comments that objectively summarize your changes. This way the reviewer will know what to expect and confirm the changes by looking at the file diffs.

PR title: Update Rule “meaningful-pbi-titles/rule”

PR description: Added missing video caption + removed unnecessary brackets

Figure: Clear and concise description

Many small changes

You should summarize by saying: “Improved readability” OR “Fixed typos and grammar”

Big and complex changes

You should include a demonstration of the change. E.g. A screenshot to show text/UI changes, or a Done video to demo functionality changes.

We open source. Powered by GitHub