[gentoo-portage-dev] [PATCH 0/3] Let's standardise commit messages

[gentoo-portage-dev] [PATCH 0/3] Let's standardise commit messages

[Alexander Berntsen]

The first two patches here are not interesting. The first one makes
DEVELOPING cap at the same width as README. The second adds a "duh"
paragraph on commits. They are only bundled with what I really wanna
talk about because I need ACKs to push them anyway. (Please ACK them,
someone.)

So what I really wanna talk about are commit messages. They are sort of
a mess. Let's just standardise them to something sane. I believe my
suggestions are sane, and pretty much "what everybody does". The reason
I wanna do "#number" for bugs is because a) we need the number for easy
grep and of course to look up the relevant bug, and b) because '#' is a
very grepable char for looking up recently fixed bugs with head or
whatever.

No bikeshedding, please. These are not very interesting things to talk
about. Let's just form a decision. Object if you have an objection. If
not, give me an ACK.

Alexander Berntsen (3):
  DEVELOPING: Cap at 72 columns
  DEVELOPING: Add note on commits
  DEVELOPING: Add note on commit messages

 DEVELOPING | 98 +++++++++++++++++++++++++++++++++++++++++---------------------
 1 file changed, 65 insertions(+), 33 deletions(-)

-- 
1.8.3.2

[gentoo-portage-dev] [PATCH 1/3] DEVELOPING: Cap at 72 columns

[Alexander Berntsen]

---
Nothing to see here, move along.

 DEVELOPING | 71 +++++++++++++++++++++++++++++++++-----------------------------
 1 file changed, 38 insertions(+), 33 deletions(-)

diff --git a/DEVELOPING b/DEVELOPING
index 40b4ca2..1f5087a 100644
--- a/DEVELOPING
+++ b/DEVELOPING
@@ -1,37 +1,39 @@
 Code Guidelines
 ---------------
-A few code guidelines to try to stick to, please comment if none of these make
-sense, they are pretty basic and mostly apply to old code.  However for people
-who are looking at current code, they make take up bad habits that exist in the
-current codebase.
+A few code guidelines to try to stick to, please comment if none of
+these make sense, they are pretty basic and mostly apply to old code.
+However for people who are looking at current code, they make take up
+bad habits that exist in the current codebase.
 
 Python Version
 --------------
 
-Python 2.6 is the minimum supported version, since it is the first version to
-support Python 3 syntax. All exception handling should use Python 3 'except'
-syntax, and the print function should be used instead of Python 2's print
-statement (from __future__ import print_function).
+Python 2.6 is the minimum supported version, since it is the first
+version to support Python 3 syntax. All exception handling should use
+Python 3 'except' syntax, and the print function should be used instead
+of Python 2's print statement (from __future__ import print_function).
 
 Dependencies
 ------------
 
-Python and Bash should be the only hard dependencies. Any other dependencies,
-including external Python modules that are not included with Python itself,
-must be optionally enabled by run-time detection.
+Python and Bash should be the only hard dependencies. Any other
+dependencies, including external Python modules that are not included
+with Python itself, must be optionally enabled by run-time detection.
 
 Tabs
 ----
 
-The current code uses tabs, not spaces.  Keep whitespace usage consistent
-between files.  New files should use tabs.  Space is sometimes used for
-indentation in Python code.  Tab stop should for this reason be set to 4.
+The current code uses tabs, not spaces.  Keep whitespace usage
+consistent between files.  New files should use tabs.  Space is
+sometimes used for indentation in Python code.  Tab stop should for this
+reason be set to 4.
 
 Line-Wrapping
 -------------
 
-Lines should typically not be longer than 80 characters; if they are an attempt
-should be made to wrap them.  Move code to the line below and indent once (\t).
+Lines should typically not be longer than 80 characters; if they are an
+attempt should be made to wrap them.  Move code to the line below and
+indent once (\t).
 
 errors.append(MalformedMetadata(
 	errors.DESCRIPTION_TOO_LONG_ERROR % \
@@ -45,9 +47,10 @@ errors.append(MalformedMetadata(
               (length, max_desc_len),
               attr='DESCRIPTION.toolong')
 
-The mixing of tabs and spaces means other developers can't read what you did.
-This is why the python peps state spaces over tabs; because with spaces the line
-wrapping is always clear (but you cannot convert spaces as easily as tabwidth).
+The mixing of tabs and spaces means other developers can't read what you
+did. This is why the python peps state spaces over tabs; because with
+spaces the line wrapping is always clear (but you cannot convert spaces
+as easily as tabwidth).
 
 Comparisons
 -----------
@@ -78,9 +81,9 @@ Generally you can do two things here, if you are messing with defaults..
 
 dict.get(foo, some_default)
 
-will try to retrieve foo from dict, if there is a KeyError, will insert foo
-into dict with the value of some_default.  This method is preferred in cases where
-you are messing with defaults:
+will try to retrieve foo from dict, if there is a KeyError, will insert
+foo into dict with the value of some_default.  This method is preferred
+in cases where you are messing with defaults:
 
 try:
 	dict[foo]
@@ -114,7 +117,8 @@ YES:
 NO:
   import os,sys,time
 
-When importing from a module, you may import more than 1 thing at a time.
+When importing from a module, you may import more than 1 thing at a
+time.
 
 YES:
   from portage.module import foo, bar, baz
@@ -139,9 +143,9 @@ NO:
   import sys
 
 Try not to import large numbers of things into the namespace of a module.
-I realize this is done all over the place in current code but it really makes it
-a pain to do code reflection when the namespace is cluttered with identifiers
-from other modules.
+I realize this is done all over the place in current code but it really
+makes it a pain to do code reflection when the namespace is cluttered
+with identifiers from other modules.
 
 YES:
 
@@ -153,14 +157,15 @@ from portage.output import bold, create_color_func, darkgreen, \
   green, nocolor, red, turquoise, yellow
 
 The YES example imports the 'output' module into the current namespace.
-The negative here is having to use output.COLOR all over the place instead of
-just COLOR.  However it means during introspection of the current namespace
-'green','red', 'yellow', etc. will not show up.
+The negative here is having to use output.COLOR all over the place
+instead of just COLOR.  However it means during introspection of the
+current namespace 'green','red', 'yellow', etc. will not show up.
 
-The NO example just imports a set of functions from the output module.  It is
-somewhat annoying because the import line needs to be modified when functions
-are needed and often unused functions are left in the import line until someone
-comes along with a linter to clean up (does not happen often).
+The NO example just imports a set of functions from the output module.
+It is somewhat annoying because the import line needs to be modified
+when functions are needed and often unused functions are left in the
+import line until someone comes along with a linter to clean up (does
+not happen often).
 
 
 Releases
-- 
1.8.3.2

[gentoo-portage-dev] [PATCH 2/3] DEVELOPING: Add note on commits

[Alexander Berntsen]

---
Boilerplate text, nothing to see here either.

 DEVELOPING | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/DEVELOPING b/DEVELOPING
index 1f5087a..c6004ec 100644
--- a/DEVELOPING
+++ b/DEVELOPING
@@ -167,6 +167,13 @@ when functions are needed and often unused functions are left in the
 import line until someone comes along with a linter to clean up (does
 not happen often).
 
+Commits
+-------
+
+Prefer small commits that change specific things to big commits that
+change a lot of unrelated things.  This makes it easier to see what
+parts of the system have actually changed.  It also makes it easier to
+cherry-pick and revert commits. Use your commonsense!
 
 Releases
 --------
-- 
1.8.3.2

[gentoo-portage-dev] [PATCH 3/3] DEVELOPING: Add note on commit messages

[Alexander Berntsen]

---
 DEVELOPING | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/DEVELOPING b/DEVELOPING
index c6004ec..a34dda5 100644
--- a/DEVELOPING
+++ b/DEVELOPING
@@ -175,6 +175,26 @@ change a lot of unrelated things.  This makes it easier to see what
 parts of the system have actually changed.  It also makes it easier to
 cherry-pick and revert commits. Use your commonsense!
 
+Commit messages
+---------------
+
+Commit messages should be in the imperative mood with a capitalised
+header, optionally followed by a newline and a more detailed explanatory
+text.  The headline should be capped at 50 characters, the detailed text
+at 72.  Prefix the message with the component you touched if this makes
+sense.  Postfix the message with the bug it fixes, if it does.  Example:
+
+"
+emerge: Fix --tree output (#555555)
+
+Make sure newlines appear where they are supposed to. Fix a bug with
+colourisation of --tree output when used in tandem with --verbose
+--pretend --ask.
+"
+
+For a more detailed explanation (and rationalisation) of these rules:
+<http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html>
+
 Releases
 --------
 
-- 
1.8.3.2

Re: [gentoo-portage-dev] [PATCH 3/3] DEVELOPING: Add note on commit messages

[Brian Dolbec]

On Thu, 27 Mar 2014 13:48:40 +0100
Alexander Berntsen <bernalex@gentoo.org> wrote:

> ---
>  DEVELOPING | 20 ++++++++++++++++++++
>  1 file changed, 20 insertions(+)
> 
> diff --git a/DEVELOPING b/DEVELOPING
> index c6004ec..a34dda5 100644
> --- a/DEVELOPING
> +++ b/DEVELOPING
> @@ -175,6 +175,26 @@ change a lot of unrelated things.  This makes it
> easier to see what parts of the system have actually changed.  It
> also makes it easier to cherry-pick and revert commits. Use your
> commonsense! 
> +Commit messages
> +---------------
> +
> +Commit messages should be in the imperative mood with a capitalised
> +header, optionally followed by a newline and a more detailed
> explanatory +text.  The headline should be capped at 50 characters,
> the detailed text +at 72.  Prefix the message with the component you
> touched if this makes +sense.  Postfix the message with the bug it
> fixes, if it does.  Example: +
> +"
> +emerge: Fix --tree output (#555555)
> +
> +Make sure newlines appear where they are supposed to. Fix a bug with
> +colourisation of --tree output when used in tandem with --verbose
> +--pretend --ask.
> +"
> +
> +For a more detailed explanation (and rationalisation) of these rules:
> +<http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html>
> +
>  Releases
>  --------
>  

No, Willikins works with Bug 555555, not #555555.

so stick with (bug 555555) format

or if your worried about the space since bug is 2 char. longer than #,
drop the 2 () characters. It'll be the same length so:

+emerge: Fix --tree output bug 555555


-- 
Brian Dolbec <dolsen>

Re: [gentoo-portage-dev] [PATCH 1/3] DEVELOPING: Cap at 72 columns

[Brian Dolbec]

On Thu, 27 Mar 2014 13:48:38 +0100
Alexander Berntsen <bernalex@gentoo.org> wrote:

> ---
> Nothing to see here, move along.
> 
do it.
-- 
Brian Dolbec <dolsen>

Re: [gentoo-portage-dev] [PATCH 2/3] DEVELOPING: Add note on commits

[Brian Dolbec]

On Thu, 27 Mar 2014 13:48:39 +0100
Alexander Berntsen <bernalex@gentoo.org> wrote:

> ---
> Boilerplate text, nothing to see here either.
> 
>  DEVELOPING | 7 +++++++
>  1 file changed, 7 insertions(+)
> 
> diff --git a/DEVELOPING b/DEVELOPING
> index 1f5087a..c6004ec 100644
> --- a/DEVELOPING
> +++ b/DEVELOPING
> @@ -167,6 +167,13 @@ when functions are needed and often unused
> functions are left in the import line until someone comes along with
> a linter to clean up (does not happen often).
>  
> +Commits
> +-------
> +
> +Prefer small commits that change specific things to big commits that
> +change a lot of unrelated things.  This makes it easier to see what
> +parts of the system have actually changed.  It also makes it easier
> to +cherry-pick and revert commits. Use your commonsense!
>  
>  Releases
>  --------

ack

-- 
Brian Dolbec <dolsen>

[gentoo-portage-dev] [PATCH] DEVELOPING: Add note on commit messages

[Alexander Berntsen]

---
Following Brian and I having a chat yesterday, here's an update. It now
uses "(bug 555555)" instead of "#555555", because of Willikins.

 DEVELOPING | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/DEVELOPING b/DEVELOPING
index c6004ec..b2b0a19 100644
--- a/DEVELOPING
+++ b/DEVELOPING
@@ -175,6 +175,26 @@ change a lot of unrelated things.  This makes it easier to see what
 parts of the system have actually changed.  It also makes it easier to
 cherry-pick and revert commits. Use your commonsense!
 
+Commit messages
+---------------
+
+Commit messages should be in the imperative mood with a capitalised
+header, optionally followed by a newline and a more detailed explanatory
+text.  The headline should be capped at 50 characters, the detailed text
+at 72.  Prefix the message with the component you touched if this makes
+sense.  Postfix the message with the bug it fixes, if it does.  Example:
+
+"
+emerge: Fix --tree output (bug 555555)
+
+Make sure newlines appear where they are supposed to. Fix a bug with
+colourisation of --tree output when used in tandem with --verbose
+--pretend --ask.
+"
+
+For a more detailed explanation (and rationalisation) of these rules:
+<http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html>
+
 Releases
 --------
 
-- 
1.8.3.2

Re: [gentoo-portage-dev] [PATCH 2/3] DEVELOPING: Add note on commits

[David James]

[-- Attachment #1: Type: text/plain, Size: 1015 bytes --]

On Thu, Mar 27, 2014 at 5:48 AM, Alexander Berntsen <bernalex@gentoo.org>wrote:

> ---
> Boilerplate text, nothing to see here either.
>
>  DEVELOPING | 7 +++++++
>  1 file changed, 7 insertions(+)
>
> diff --git a/DEVELOPING b/DEVELOPING
> index 1f5087a..c6004ec 100644
> --- a/DEVELOPING
> +++ b/DEVELOPING
> @@ -167,6 +167,13 @@ when functions are needed and often unused functions
> are left in the
>  import line until someone comes along with a linter to clean up (does
>  not happen often).
>
> +Commits
> +-------
> +
> +Prefer small commits that change specific things to big commits that
> +change a lot of unrelated things.  This makes it easier to see what
> +parts of the system have actually changed.  It also makes it easier to
> +cherry-pick and revert commits. Use your commonsense!
>

s/commonsense/common sense/, since commonsense is an
adjective<http://www.thehindu.com/books/know-your-english/know-your-english-is-common-sense-one-word-or-two/article3675226.ece>and
"common sense" is a noun :)

[-- Attachment #2: Type: text/html, Size: 1445 bytes --]

[gentoo-portage-dev] [PATCH] DEVELOPING: Add note on commits

[Alexander Berntsen]

---
Whoops! Spellcheckers are not overly helpful when your typo is a legal
word. Good catch! :-)


 DEVELOPING | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/DEVELOPING b/DEVELOPING
index 1f5087a..9731610 100644
--- a/DEVELOPING
+++ b/DEVELOPING
@@ -167,6 +167,13 @@ when functions are needed and often unused functions are left in the
 import line until someone comes along with a linter to clean up (does
 not happen often).
 
+Commits
+-------
+
+Prefer small commits that change specific things to big commits that
+change a lot of unrelated things.  This makes it easier to see what
+parts of the system have actually changed.  It also makes it easier to
+cherry-pick and revert commits. Use your common sense!
 
 Releases
 --------
-- 
1.8.3.2

Re: [gentoo-portage-dev] [PATCH 0/3] Let's standardise commit messages

[Brian Dolbec]

On Thu, 27 Mar 2014 13:48:37 +0100
Alexander Berntsen <bernalex@gentoo.org> wrote:

> The first two patches here are not interesting. The first one makes
> DEVELOPING cap at the same width as README. The second adds a "duh"
> paragraph on commits. They are only bundled with what I really wanna
> talk about because I need ACKs to push them anyway. (Please ACK them,
> someone.)
> 
> So what I really wanna talk about are commit messages. They are sort
> of a mess. Let's just standardise them to something sane. I believe my
> suggestions are sane, and pretty much "what everybody does". The
> reason I wanna do "#number" for bugs is because a) we need the number
> for easy grep and of course to look up the relevant bug, and b)
> because '#' is a very grepable char for looking up recently fixed
> bugs with head or whatever.
> 
> No bikeshedding, please. These are not very interesting things to talk
> about. Let's just form a decision. Object if you have an objection. If
> not, give me an ACK.
> 
> Alexander Berntsen (3):
>   DEVELOPING: Cap at 72 columns
>   DEVELOPING: Add note on commits
>   DEVELOPING: Add note on commit messages
> 
>  DEVELOPING | 98
> +++++++++++++++++++++++++++++++++++++++++--------------------- 1 file
> changed, 65 insertions(+), 33 deletions(-)
> 


Ack on the revised commits.  go ahead and commit.  :) Thanks
-- 
Brian Dolbec <dolsen>