Added instructions on contributing and requesting changes #132
Conversation
introduction/how-to-contribute.md
Outdated
| 1. Anyone can participate in reviews, not only Eiffel team members. | ||
| 1. A Pull Request should be approved by at least two Eiffel team members (including the one doing the merging). For this to function well, the above point on participation is critical. | ||
| 1. Do not feel any pressure to merge Pull Requests. Unless you feel confident about what you are doing, don't press that big green button. Instead, ask a more senior member to make the decision. | ||
| 1. When squashing and merging, ensure that the description reflects the change. Detailing every individual commit in the Pull Request is unnecessary, as they are squashed anyway. Instead, describe the change as a single thing. That description should always include an Issue reference. A lot of the time a descriptive title and an Issue reference is all that is needed. |
There was a problem hiding this comment.
Minor improvement: Also state that the description should state what you sort of get when you include the commit (compared not including the commit).
There was a problem hiding this comment.
Sorry, I don't follow...?
There was a problem hiding this comment.
It is the what vs. how dimension. I have seen a few too many descriptions on the level of what has changed, but nothing on why.
See bullet 7 https://chris.beams.io/posts/git-commit/ for a more general discussion on this.
There was a problem hiding this comment.
Ok, I'm with you. Actually that's a pretty good guide, didn't read that one before (but the xkcd strip is brilliant!).
To emphasize the need of providing context, rather than just listing changes.
introduction/how-to-contribute.md
Outdated
| 1. Anyone can participate in reviews, not only Eiffel team members. | ||
| 1. A Pull Request should be approved by at least two Eiffel team members (including the one doing the merging). For this to function well, the above point on participation is critical. | ||
| 1. Do not feel any pressure to merge Pull Requests. Unless you feel confident about what you are doing, don't press that big green button. Instead, ask a more senior member to make the decision. | ||
| 1. When squashing and merging, ensure that the description reflects the change. Detailing every individual commit in the Pull Request is unnecessary, as they are squashed anyway. Instead, describe the change as a single thing. That description should always include an Issue reference, and should focus on WHY a the change was made, to provide the reader with context. See [this excellent guide](https://chris.beams.io/posts/git-commit) on writing good commit messages. |
There was a problem hiding this comment.
"and should focus on WHY a the change was made"
There was a problem hiding this comment.
Doh! Fixed.
|
👍 |
|
I'll go ahead and merge this tomorrow, unless anyone objects. |
As per issue #131.