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.

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: make commit guidelines easier to reference #11732

Closed
wants to merge 1 commit into from
Closed
Changes from all commits
Commits
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
43 changes: 20 additions & 23 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,15 +100,28 @@ $ git commit
Writing good commit logs is important. A commit log should describe what
changed and why. Follow these guidelines when writing one:

1. The first line should be 50 characters or less and contain a short
description of the change. All words in the description should be in
lowercase with the exception of proper nouns, acronyms, and the ones that
refer to code, like function/variable names. The description should
be prefixed with the name of the changed subsystem and start with an
imperative verb. Example: "net: add localAddress and localPort
to Socket"
1. The first line should:
- contain a short description of the change
- be 50 characters or less
- be entirely in lowercase with the exception of proper nouns, acronyms, and
the words that refer to code, like function/variable names
- be prefixed with the name of the changed subsystem and start with an
imperative verb. Examples: "net: add localAddress and localPort
to Socket", "src: fix typos in node_lttng_provider.h"
- be meaningful; it is what other people see when they
run `git shortlog` or `git log --oneline`.<br>
Copy link
Member

Choose a reason for hiding this comment

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

I think the html <br> is a typo here?

Copy link
Contributor Author

@bf4 bf4 Mar 12, 2017

Choose a reason for hiding this comment

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

🤔 I thought the line break improved readability

Copy link
Contributor

Choose a reason for hiding this comment

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

I think you can put a blank line in the file to get a break

Copy link
Contributor Author

@bf4 bf4 Mar 30, 2017

Choose a reason for hiding this comment

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

@sam-github I made the 80 char change, but left the <br>. Please review my screenshots and let me know which you prefer.

With brwithout brwith blank line

now

Copy link
Contributor

Choose a reason for hiding this comment

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

I can't tell the difference, they all look fine

Check the output of `git log --oneline files/you/changed` to find out
what subsystem (or subsystems) your changes touch
2. Keep the second line blank.
3. Wrap all other lines at 72 columns.
- If your patch fixes an open issue, you can add a reference to it at the end
of the log. Use the `Fixes:` prefix and the full issue URL. For other references
use `Refs:`. For example:
```txt
Fixes: https://github.com/nodejs/node/issues/1337
Refs: http://eslint.org/docs/rules/space-in-parens.html
Refs: https://github.com/nodejs/node/pull/3615
```
Copy link
Contributor Author

@bf4 bf4 Mar 7, 2017

Choose a reason for hiding this comment

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

❓ Maybe also check your commit for spelling and clarity ? :)


A good commit log can look something like this:

Expand All @@ -123,22 +136,9 @@ The body of the commit message can be several paragraphs, and
please do proper word-wrap and keep columns shorter than about
72 characters or so. That way, `git log` will show things
nicely even when it is indented.
```

The header line should be meaningful; it is what other people see when they
run `git shortlog` or `git log --oneline`.

Check the output of `git log --oneline files_that_you_changed` to find out
what subsystem (or subsystems) your changes touch.

If your patch fixes an open issue, you can add a reference to it at the end
of the log. Use the `Fixes:` prefix and the full issue URL. For other references
use `Refs:`. For example:

```txt
Fixes: https://github.com/nodejs/node/issues/1337
Refs: http://eslint.org/docs/rules/space-in-parens.html
Refs: https://github.com/nodejs/node/pull/3615
```

### Step 4: Rebase
Expand Down Expand Up @@ -203,9 +203,6 @@ core modules.
$ git push origin my-branch
```

Go to https://github.com/yourusername/node and select your branch.
Click the 'Pull Request' button and fill out the form.

Pull requests are usually reviewed within a few days.

### Step 7: Discuss and update
Expand Down