From 241149062fee932797e6e1b61cd1c3ee58ab3c06 Mon Sep 17 00:00:00 2001 From: tlinjordet Date: Fri, 23 Apr 2021 12:04:44 +0200 Subject: [PATCH 1/3] Create Git_commit.md --- Git_commit.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 Git_commit.md diff --git a/Git_commit.md b/Git_commit.md new file mode 100644 index 0000000..dbb90a0 --- /dev/null +++ b/Git_commit.md @@ -0,0 +1,37 @@ +# IAI Git Commit Message Style Guide + +Initially adapted from a [blog post](https://chris.beams.io/posts/git-commit/). + +## Commit message objectives + +We want commit messages to be concise and consistent, to communicate the context of a change. + + * The `diff` contains *what* changes were made, the `commit` explains *why* they were made. + * Consistent commit message style + * simplifies both reading and writing commit messages, and + * supports communication and collaboration. + +## Writing style conventions + + * Write complete and grammatical sentences in English, with regular punctuation, e.g, finishing with a period. + * Use imperative tense, to tersely convey the purpose of the change. + * For example, "Defibrilate the crustacean Jazz mountain, recursively." + * Use GitHub flavored markdown syntax where needed. + +## Spacing + + * There should be an empty line before and after headers. + +## Markup + + * Top-level lists are marked by `*`, second, third, etc. levels below are marked by `-`. + * Indent items with 2 spaces. + +``` + * List item 1 + * List item 2 + - Sub item 21 + - Sub item 211 + - Sub item 22 + * List item 3 +``` From d43d134c2de47e4f2ea25fc1a6e1e8a8d35e9b90 Mon Sep 17 00:00:00 2001 From: tlinjordet Date: Fri, 23 Apr 2021 13:15:07 +0200 Subject: [PATCH 2/3] Update Git_commit.md --- Git_commit.md | 38 +++++++++++++++++++++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/Git_commit.md b/Git_commit.md index dbb90a0..8bc646f 100644 --- a/Git_commit.md +++ b/Git_commit.md @@ -6,11 +6,47 @@ Initially adapted from a [blog post](https://chris.beams.io/posts/git-commit/). We want commit messages to be concise and consistent, to communicate the context of a change. - * The `diff` contains *what* changes were made, the `commit` explains *why* they were made. + * The `diff` contains *what* and *how* changes were made, the `commit` primarily explains *why* they were made. * Consistent commit message style * simplifies both reading and writing commit messages, and * supports communication and collaboration. +## Context + +There are different ways and contexts whereby a commit message is added, but for simplicity we assume you made some changes, and did the following commands in the terminal: +``` +git add . +git commit +``` + +You will then have vi open and provide the following starting point: +``` + +# Please enter the commit message for your changes. Lines starting +# with '#' will be ignored, and an empty message aborts the commit. +# +# On branch master +# Your branch is up to date with 'origin/master'. +# +# Changes to be committed: +# new file: foo +# +``` + +And then your job is to write a good commit message! Document why you are making the commit and the associated changes. + +## Rules + +You should at least write a single line if your commit only needs a brief explanation. We'll call this the subject, whether or not you also write a longer text, called the body, below the subject. + +### Subject + +The subject should be + * captialized, e.g. *Combine the Christmas lighbulbs*, + * maximum 50 characters, + * written with no terminating period, and + * the subject should be written in the *imperative mood*. + ## Writing style conventions * Write complete and grammatical sentences in English, with regular punctuation, e.g, finishing with a period. From 16997296c6c6207ad71d6effb893fef7ee19c4c0 Mon Sep 17 00:00:00 2001 From: tlinjordet Date: Fri, 23 Apr 2021 13:28:11 +0200 Subject: [PATCH 3/3] Update Git_commit.md --- Git_commit.md | 63 ++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 47 insertions(+), 16 deletions(-) diff --git a/Git_commit.md b/Git_commit.md index 8bc646f..08baae9 100644 --- a/Git_commit.md +++ b/Git_commit.md @@ -47,27 +47,58 @@ The subject should be * written with no terminating period, and * the subject should be written in the *imperative mood*. -## Writing style conventions +It's helpful to think that the subject should complete the sentence - * Write complete and grammatical sentences in English, with regular punctuation, e.g, finishing with a period. - * Use imperative tense, to tersely convey the purpose of the change. - * For example, "Defibrilate the crustacean Jazz mountain, recursively." - * Use GitHub flavored markdown syntax where needed. + * If applied, this commit will *your subject line here* -## Spacing +### Body - * There should be an empty line before and after headers. +If you need more than one 50 character line to explain your change, write a body under the subject in the commit message. -## Markup +The body should be + * separated from the subject by one blank line, + * (manually) wrapped at 72 characters, and + * an explanation of why and what was changed, not how it works. - * Top-level lists are marked by `*`, second, third, etc. levels below are marked by `-`. - * Indent items with 2 spaces. +### Issue tracking + +Put references to repository issues at the bottom of the body, as in the example. + +## Example + +This example is taken directly from the [blog post](https://chris.beams.io/posts/git-commit/). ``` - * List item 1 - * List item 2 - - Sub item 21 - - Sub item 211 - - Sub item 22 - * List item 3 +Summarize changes in around 50 characters or less + +More detailed explanatory text, if necessary. Wrap it to about 72 +characters or so. In some contexts, the first line is treated as the +subject of the commit and the rest of the text as the body. The +blank line separating the summary from the body is critical (unless +you omit the body entirely); various tools like `log`, `shortlog` +and `rebase` can get confused if you run the two together. + +Explain the problem that this commit is solving. Focus on why you +are making this change as opposed to how (the code explains that). +Are there side effects or other unintuitive consequences of this +change? Here's the place to explain them. + +Further paragraphs come after blank lines. + + - Bullet points are okay, too + + - Typically a hyphen or asterisk is used for the bullet, preceded + by a single space, with blank lines in between, but conventions + vary here + +If you use an issue tracker, put references to them at the bottom, +like this: + +Resolves: #123 +See also: #456, #789 ``` + + +## What's the use? + +You can look at the commit messages later, e.g. by the command `git log`.