From: Eric Sunshine <sunshine <at> sunshineco.com> Subject: Re: [PATCH v5 0/6] git help: group common commands by theme Newsgroups: gmane.comp.version-control.git Date: 2015-05-11 05:52:50 GMT (1 day, 12 hours and 19 minutes ago) On Sat, May 9, 2015 at 1:17 PM, Sébastien Guimmara <sebastien.guimmara <at> gmail.com> wrote: > Sébastien Guimmara (6): > generate-cmdlist: parse common group commands > help.c: output the typical Git workflow > command-list.txt: group common commands by theme > Makefile: update to new command-list.txt format > new-command.txt: mention the common command groups > cmd-list.perl: ignore all lines until [commands] When preparing a patch series, it's important to think not just about the final result but also the state of the project at any point within the series. The project should remain in a working state (not broken and not regressed) at all steps during the patch series[1]. As each patch is applied, you should be able to build git successfully, and run "git help" and get expected results (for that point in the series). If you can't do either, then there is a problem. Unfortunately, the organization of this series (v5) breaks the build and raw functionality from the get-go. Here is a proposed organization which will keep the project in a sane state as each patch is applied: patch 1: [x] Add a [commands] header to command-list.txt [x] check-docs in Makefile, and either [x] cmd-list.perl to ignore everything up to and including [commands]. You're not actually doing any classification in command-list.txt at this point, but instead merely preparing the machinery to deal with the [commands] header (and the [common] section which you will add in a subsequent patch). patch 2: [x] Add the [common] block to command-list.txt and tag each of the common commands with an attribute from [common]. Do *not*, however, remove the old "common" tag at this point since generate-cmdlist.sh still needs it. patch 3: [x] Introduce generate-cmdlist.awk and [x] retire generate-cmdlist.sh, [x] along with the associated Makefile changes. This patch should be exactly the one I posted[2] (between the "--- >8 ---" lines), along with the minor fixup[3]. The changes in that patch are a logical unit, so they shouldn't be split up (as you did in v5 between patches 1/6 and 4/6). patch 4: [x] Drop the old "common" attribute from command-list.txt items since it's no longer needed by any machinery. patch 5: Update help.c to group and sort the commands using the new common_cmd_groups[] array and common_commands[].group field. patch 6 [optional]: Update howto/new-command.txt. Alternately, and probably preferably, fold this documentation update into patch 2 and omit this step. [1]: This is called "preserving bisectability". See "git bisect". [2]: http://article.gmane.org/gmane.comp.version-control.git/268598 [3]: http://article.gmane.org/gmane.comp.version-control.git/268599 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html