@@ -57,26 +57,44 @@ Beginners are encouraged to pick up issues that are marked `help wanted`. It is
57a good idea to update the issue expressing your intent so that others do not
57a good idea to update the issue expressing your intent so that others do not
58duplicate the effort and people with a background on the issue can help.
58duplicate the effort and people with a background on the issue can help.
60−### Changeset in a PR
60+### Structuring Pull Requests
62−* Please make sure that a single PR contains a single logical changeset. That
62+__Lean PR:__ Please keep the reviewer in mind when sending pull
63− helps the reviewers in quickly understanding and reviewing the change.
63+requests. Use one PR for each logical changeset. A lean and thin
64+PR with one independent logical change is more likely to be reviewed and
65+merged quickly than a big monolithic PR with several unrelated changes.
67+__PR Dependencies:__ If your change depends on an earlier PR you can
68+create a branch from the old PR's branch, and raise a new PR targeting
69+to merge into the old PR branch. Do not push the commits to the same PR
70+just because the commit depends on that PR.
64−* You are encouraged to group a logically related set of changes into a single
72+__Commits:__ You are encouraged to group a logically related set of
65− commit. When the overall changeset is largish you can divide it into
73+changes into a single commit. When the overall changeset is largish you
66− multiple smaller commits, with each commit having a logically grouped
74+can divide it into multiple smaller commits, with each commit having
67− changeset and the title summarizing the logical grouping. Always keep in
75+a logically grouped changeset and the title summarizing the logical
68− mind a logical division helps reviewers understand and review your code
76+grouping. Always keep in mind a logical division helps reviewers
77+understand and review your code quickly, easier history tracking and
69− quickly, easier history tracking and when required clean reversal changes.
78+when required clean reversal changes.
70−* If your commits reflect how you fixed intermediate problems during testing
79+
71− or made random changes at different times you may have to squash your changes
80+__Functional Changes:__ Keep the reviewer in mind when making
72− (`git rebase -i`) into a single commit or logically related set of commits.
73−* Please resist the temptation to make style related changes to surrounding
81+changes. Please resist the temptation to make style related changes to
74− code unless you are changing that code anyway . Make sure that your
82+surrounding code unless you are changing that code anyway . Whenever
83+possible, try to separate unrelated refactoring changes which do not
84+affect functionality in separate commits so that it is easier for the
85+reviewer to verify functional changes.
87+__Style Changes:__ Make sure that your IDE/Editor is not automatically
75− IDE/Editor is not automatically making sweeping style changes to all the
88+making sweeping style changes to all the files you are editing. That
76− files you are editing. That makes separating the signal from the noise
89+makes separating the signal from the noise very difficult and makes
77− very difficult and makes everything harder. If you would like to make style
90+everything harder. If you would like to make style related changes
78− related changes then please send a separate PR with just those changes and no
91+then please send a separate PR with just those changes and no other
79− other functionality changes.
92+functionality changes.
94+__Rebasing:__ If your commits reflect how you fixed intermediate
95+problems during testing or made random changes at different times you
96+may have to squash your changes (`git rebase -i`) into a single commit
97+or logically related set of commits.
81### Resolving Conflicts
99### Resolving Conflicts