Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: update onboarding PR landing info #8479

Closed
wants to merge 2 commits into from
Closed

doc: update onboarding PR landing info #8479

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9495626
doc: update onboarding PR landing info
Trott Sep 10, 2016
efa0bf0
squash: address nits
Trott Sep 10, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 16 additions & 10 deletions doc/onboarding.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -170,18 +170,24 @@ Landing a PR
* `git rebase -i upstream/master`
* squash into logical commits if necessary
* `./configure && make -j8 test` (`-j8` builds node in parallel with 8 threads. adjust to the number of cores (or processor-level threads) your processor has (or slightly more) for best results.)
* Amend the commit description
* commits should follow `subsystem[,subsystem]: small description\n\nbig description\n\n<metadata>`
* first line 50 columns, all others 72
* add metadata:
* `Fixes: <full-issue-url>`
* `Reviewed-By: human <email>`
* Easiest to use `git log` then do a search
* (`/Name` + `enter` (+ `n` as much as you need to) in vim)
* Only include collaborators who have commented `LGTM`
* Amend the commit description.
* Commits should be of the form `subsystem[,subsystem]: small description\n\nbig description\n\n<metadata>`
* The first line should not exceed 50 characters.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe specify that the description should use the imperative mood.

Copy link
Member Author

@Trott Trott Sep 10, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like it, but that gets a little trickier and starts leaking into other docs:

  • Commit message formatting requirements are in CONTRIBUTING.md and belong there, IMO. This doc should just link to that section (except for metadata format, since that's Collaborator-specific).
  • The CONTRIBUTING.md should include the imperative mood requirement. I don't think it does right now. So it will need to be updated too.
  • There may be some discussion around whether using the term imperative mood will be well-understood or is completely accurate. We may want to go with something more like "should start with a present-tense verb". Not sure but there seems to be a risk of bike-shedding.

For those reasons, if it's OK with you, I'd prefer to make the whole adjusting-the-requirements-for-the-commit-message thing be a separate pull request. (Feel free to open it yourself if you wish!)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Commit message formatting requirements are in CONTRIBUTING.md and belong there, IMO.

I agree but in this case I would argue that the whole sentence ("The first line should not exceed 50 characters.") belongs to CONTRIBUTING.md.

That said, I'm totally fine with this as is, it's really nitpicking :)

* The remaining lines (except for metadata lines) should wrap at 72 characters.
* Add required metadata:
* `PR-URL: <full-pr-url>`
* `Reviewed-By: <collaborator name> <collaborator email>`
* Easiest to use `git log`, then do a search.
* In vim: `/Name` + `enter` (+ `n` as much as you need to)
* Only include collaborators who have commented `LGTM`.
* Add additional metadata as appropriate:
* `Fixes: <full-issue-url>`
* Full URL of GitHub issue that the PR fixes.
* This will automatically close the PR when the commit lands in master.
* `Refs: <full-url>`
* Full URL of material that might provide additional useful information or context to someone trying to understand the change set or the thinking behind it.
* `git push upstream master`
* close the original PR with "Landed in `<commit hash>`".
* Close the pull request with a "Landed in `<commit hash>`" comment.


## exercise: make PRs adding yourselves to the README
Expand Down