[v3,0/2] add usage-strings ci check and amend remaining usage strings

Message

Philippe Blain via GitGitGadget Feb. 23, 2022, 2:27 p.m. UTC

This patch series completely fixes #636.

The issue is about amending the usage-strings (for command flags such as -h,
-v etc.) which do not follow the style convention/guide. There was a PR
[https://github.com/gitgitgadget/git/pull/920] addressing this issue but as
Johannes [https://github.com/dscho] said in his comment
[https://github.com/gitgitgadget/git/issues/636#issuecomment-1018660439],
there are some files that still have those kind of usage strings. Johannes
also suggested to add a CI check under ci/test-documentation.sh to check the
usage strings.

In this version, the previously single commit is split into two commits (
one addressing amending of usage strings and another is for adding the style
checks to parse_options_check()) and the checks are simplified.

Changes since v1:

 1. remove check-usage-strings.sh
 2. remove CI check
 3. add checks to parse-options.c
 4. modify t/t1502-rev-parse-parseopt.sh to pass the test

Until v1:

A shell script check-usage-strings.sh was introduced to check the
usage-strings. CI check for the same was also introduced.

Abhra303 (1):
  amend remaining usage strings according to style guide

Abhradeep Chakraborty (1):
  parse-options.c: add style checks for usage-strings

 builtin/bisect--helper.c      | 2 +-
 builtin/reflog.c              | 6 +++---
 builtin/submodule--helper.c   | 2 +-
 diff.c                        | 2 +-
 parse-options.c               | 6 ++++++
 t/helper/test-run-command.c   | 6 +++---
 t/t1502-rev-parse-parseopt.sh | 4 ++--
 7 files changed, 17 insertions(+), 11 deletions(-)


base-commit: e6ebfd0e8cbbd10878070c8a356b5ad1b3ca464e
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1147%2FAbhra303%2Fusage_command_amend-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1147/Abhra303/usage_command_amend-v3
Pull-Request: https://github.com/gitgitgadget/git/pull/1147

Range-diff vs v2:

 1:  902937e768d ! 1:  f425e36b7ea add usage-strings check  and amend remaining usage strings
     @@ Metadata
      Author: Abhra303 <[e-mail]>
      
       ## Commit message ##
     -    add usage-strings check  and amend remaining usage strings
     +    amend remaining usage strings according to style guide
      
          Usage strings for git (sub)command flags has a style guide that
     -    suggests - first letter should not capitalized (unless requied)
     +    suggests - first letter should not capitalized (unless required)
          and it should skip full-stop at the end of line. But there are
          some files where usage-strings do not follow the above mentioned
     -    guide. Moreover, there are no checks to verify if all usage strings
     -    are following the guide/convention or not.
     +    guide.
      
     -    Amend the usage strings that don't follow the convention/guide and
     -    add a check in the `parse_options_check()` function in `parse-options.c`
     -    to check the usage strings against the style guide.
     +    Amend the usage strings that don't follow the style convention/guide.
      
          Signed-off-by: Abhradeep Chakraborty <[e-mail]>
      
     @@ diff.c: static void prep_parse_options(struct diff_options *options)
       
       		OPT_END()
      
     - ## parse-options.c ##
     -@@ parse-options.c: static void parse_options_check(const struct option *opts)
     - 		default:
     - 			; /* ok. (usually accepts an argument) */
     - 		}
     -+		if (opts->type != OPTION_GROUP && opts->help &&
     -+			!(starts_with(opts->help, "HEAD") ||
     -+			  starts_with(opts->help, "GPG") ||
     -+			  starts_with(opts->help, "DEPRECATED") ||
     -+			  starts_with(opts->help, "SHA1")) &&
     -+			  (opts->help[0] >= 65 && opts->help[0] <= 90))
     -+			err |= optbug(opts, xstrfmt("help should not start with capital letter unless needed: %s", opts->help));
     -+		if (opts->help && !ends_with(opts->help, "...") && ends_with(opts->help, "."))
     -+			err |= optbug(opts, xstrfmt("help should not end with a dot: %s", opts->help));
     - 		if (opts->argh &&
     - 		    strcspn(opts->argh, " _") != strlen(opts->argh))
     - 			err |= optbug(opts, "multi-word argh should use dash to separate words");
     -
       ## t/helper/test-run-command.c ##
      @@ t/helper/test-run-command.c: static int quote_stress_test(int argc, const char **argv)
       	struct strbuf out = STRBUF_INIT;
     @@ t/helper/test-run-command.c: static int quote_stress_test(int argc, const char *
       		OPT_END()
       	};
       	const char * const usage[] = {
     -
     - ## t/t1502-rev-parse-parseopt.sh ##
     -@@ t/t1502-rev-parse-parseopt.sh: test_expect_success 'setup optionspec-only-hidden-switches' '
     - |
     - |some-command does foo and bar!
     - |--
     --|hidden1* A hidden switch
     -+|hidden1* a hidden switch
     - EOF
     - '
     - 
     -@@ t/t1502-rev-parse-parseopt.sh: test_expect_success 'test --parseopt help-all output hidden switches' '
     - |
     - |    some-command does foo and bar!
     - |
     --|    --hidden1             A hidden switch
     -+|    --hidden1             a hidden switch
     - |
     - |EOF
     - END_EXPECT
 -:  ----------- > 2:  9d42bdbff6c parse-options.c: add style checks for usage-strings