Re: [PATCH v10 1/5] command-list: prepare machinery for upcoming "common groups" section

On Thu, May 21, 2015 at 9:55 AM, Sébastien Guimmara
[off-list ref] wrote:

On 05/21/2015 03:48 PM, Eric Sunshine wrote:

quoted

On Thu, May 21, 2015 at 9:13 AM, Sébastien Guimmara
[off-list ref] wrote:

quoted

The ultimate goal is for "git help" to classify common commands by
group. Toward this end, a subsequent patch will add a new "common
groups" section to command-list.txt preceding the actual command list.
As preparation, teach existing command-list.txt parsing machinery, which
doesn't care about grouping, to skip over this upcoming "common groups"
section.

Signed-off-by: Eric Sunshine <redacted>
Signed-off-by: Sébastien Guimmara <redacted>
---

@@ -95,7 +95,9 @@ your language, document it in the INSTALL file.
  that categorizes commands by type, so they can be listed in appropriate
  subsections in the documentation's summary command list.  Add an entry
  for yours.  To understand the categories, look at git-commands.txt
-in the main directory.
+in the main directory.  If the new command is part of the typical Git
+workflow and you believe it common enough to be mentioned in 'git help',
+map this command to a common group in the column [common].

I think you meant to squash the documentation update into patch 2/5
where the "common groups" block is actually introduced. It doesn't
really belong in this patch which is about updating machinery in
preparation for the new block.

I don't mind squashing it with another commit, but in this case, wouldn't it
make more sense to squash it with 4/5, when the 'common' tag is removed and
the file is in its final form ?

In my mind, the most logical point at which the documentation should
start talking about the new "common coups" is when "common groups"
actually comes into existence since the new documentation is directly
related to birth of that new section of the file. The documentation
update is, at best, only very peripherally related to removal of the
old 'common' tag, so it doesn't really seem logical to tie the
documentation update to 'common' removal in 4/5. But that's just my
opinion...

quoted

Also, it's now spelled "### common groups" rather than "[common]".

actually, this [common] is not the one I added in a previous series,
but the one that was already present:

# command name      category [deprecated] [common]

Ah, right. Thanks for clarifying.