Do you include a useful description of your changes?

Updated by Tiago Araújo [SSW] 1 year ago. See history

123
<introEmbed body={<> 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

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

PR description: Changes made:

  1. Added missing video figure to embedded YouTube video
  2. Removed the unecessary closing brackets from: Use emojis. See our rule on emojis in Scrum). To: Use emojis. See our rule on emojis in Scrum

😐 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.

Categories

Rules to Better ScrumRules to Better Pull RequestsRules to Better GitHubRules to Better Communication

Acknowledgements

Adam Cogan
Tiago Araujo
Related rules

Need help?

SSW Consulting has over 30 years of experience developing awesome software solutions.

We open source.Loving SSW Rules? Star us on GitHub. Star