suggest to keep logical commits in PRs instead of squashing them

Description

For non-trivial pull requests a single commit may be very difficult to
read. It can even be more difficult when coming back months later and
trying to understand how the pull request introduced a bug or a
regression.

The developer guide already suggests a pull request should be nicely
organized in logical commits. But it is not clear about squashing them
together, only suggesting it is a good practice but not explaining
why.

Clarify the benefits of keeping a well organized commit series in the
pull request. Add a hint for the person in charge of merging about how
to squash when merging without discarding the commit series.

  1.  

    1. [DOC-XXXX](https://openedx.atlassian.net/browse/DOC-XXXX)

Add a description of your changes with links to any relevant material.

  1.  

    1.  

      1. Date Needed (optional)

If the release date of a feature is known or estimated, provide it to give reviewers guidance on turnaround time.

  1.  

    1.  

      1. Reviewers

Possible roles follow. The PR submitter checks the boxes after each reviewer finishes and gives :+1:.

  • [ ] Subject matter expert:

  • [ ] Subject matter expert:

  • [ ] Doc team review (sanity check, copy edit, or dev edit?): @edx/doc

  • [ ] Product review:

  • [ ] Partner support:

  • [ ] PM review:

FYI: Tag anyone else who might be interested in this PR here.

  1.  

    1.  

      1. Testing

  • [ ] Ran ./run_tests.sh without warnings or errors

  1.  

    1.  

      1. HTML Version (optional)

  • [ ] Build an RTD draft for your branch and add a link here

  1.  

    1.  

      1. Sandbox (optional)

  • [ ] Point to or build a sandbox for the software change and add a link here

  1.  

    1.  

      1. Post-review

  • [ ] Add a comment with the description of this change or link this PR to the next release notes task.

  • [ ] Squash commits

Status

Assignee

Ned Batchelder

Reporter

Open Source Pull Request Bot

Contributor Name

Loic Dachary

Repo

edx/edx-documentation

PR Number

1,803

Customer

None

Course

None

OSCM Assignee

None

Github Latest Action

issue_comment: created

Github Latest Action by edX

No

Github PR Last Updated At

Feb 25, 2019, 8:49 PM

Github PR Last Updated By

singuliere

Impacted Users (OSPR)

None

Impacted Environments (OSPR)

None

Feature Control (OSPR)

None

Priority

Unset
Configure