[PATCH v3 0/9] Minor improvements to CodingGuidelines and SubmittingPatches

["Josh Soref via GitGitGadget" <gitgitgadget@gmail.com>]

These are a bunch of things I've run into over my past couple of attempts to
contribute to Git.

 * Incremental punctuation/grammatical improvements
 * Update extra tags suggestions based on common usage
 * drop reference to an article that was discontinued over a decade ago
 * update GitHub references
 * harmonize non-ASCII while I'm here

Note that I'm trying to do things "in the neighborhood". It'll be slower
than me replacing things topically, but hopefully easier for others to
digest. My current estimate is a decade or two :).

Josh Soref (9):
  CodingGuidelines: move period inside parentheses
  CodingGuidelines: write punctuation marks
  SubmittingPatches: drop ref to "What's in git.git"
  SubmittingPatches: discourage new trailers
  SubmittingPatches: update extra tags list
  SubmittingPatches: provide tag naming advice
  SubmittingPatches: clarify GitHub visual
  SubmittingPatches: clarify GitHub artifact format
  SubmittingPatches: hyphenate non-ASCII

 Documentation/CodingGuidelines  |  4 ++--
 Documentation/SubmittingPatches | 33 +++++++++++++++++++++++----------
 2 files changed, 25 insertions(+), 12 deletions(-)


base-commit: 624eb90fa8f65a79396615f3c2842ac5a3743350
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1623%2Fjsoref%2Fdocumentation-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1623/jsoref/documentation-v3
Pull-Request: https://github.com/gitgitgadget/git/pull/1623

Range-diff vs v2:

  1:  b9a8eb6aa4e =  1:  b9a8eb6aa4e CodingGuidelines: move period inside parentheses
  2:  c0db8336e51 =  2:  c0db8336e51 CodingGuidelines: write punctuation marks
  3:  22d66c5b78a =  3:  22d66c5b78a SubmittingPatches: drop ref to "What's in git.git"
  4:  eac2211332f =  4:  eac2211332f SubmittingPatches: discourage new trailers
  5:  8848572fe2c =  5:  8848572fe2c SubmittingPatches: update extra tags list
  6:  8f16c7caa73 !  6:  f28c1011ba9 SubmittingPatches: improve extra tags advice
     @@ Metadata
      Author: Josh Soref <jsoref@gmail.com>
      
       ## Commit message ##
     -    SubmittingPatches: improve extra tags advice
     +    SubmittingPatches: provide tag naming advice
      
          Current statistics show a strong preference to only capitalize the first
          letter in a hyphenated tag, but that some guidance would be helpful:
     @@ Documentation/SubmittingPatches: While you can also create your own trailer if t
       encourage you to instead use one of the common trailers in this project
       highlighted above.
       
     -+Extra tags should only capitalize the very first letter, i.e. favor
     ++Only capitalize the very first letter of tags, i.e. favor
      +"Signed-off-by" over "Signed-Off-By" and "Acked-by:" over "Acked-By".
      +
       [[git-tools]]
  7:  cdb5fd0957f <  -:  ----------- SubmittingPatches: clarify GitHub visual
  8:  77576327df8 !  7:  49cef6f7c20 SubmittingPatches: clarify GitHub artifact format
     @@ Metadata
      Author: Josh Soref <jsoref@gmail.com>
      
       ## Commit message ##
     -    SubmittingPatches: clarify GitHub artifact format
     +    SubmittingPatches: clarify GitHub visual
      
     -    GitHub wraps artifacts generated by workflows in a .zip file.
     +    GitHub has two general forms for its states, sometimes they're a simple
     +    colored object (e.g. green check or red x), and sometimes there's also a
     +    colored container (e.g. green box or red circle) which contains that
     +    object (e.g. check or x).
      
     -    Internally, workflows can package anything they like in them.
     -
     -    A recently generated failure artifact had the form:
     -
     -    windows-artifacts.zip
     -      Length      Date    Time    Name
     -    ---------  ---------- -----   ----
     -     76001695  12-19-2023 01:35   artifacts.tar.gz
     -     11005650  12-19-2023 01:35   tracked.tar.gz
     -    ---------                     -------
     -     87007345                     2 files
     +    That's a lot of words to try to describe things, but in general, the key
     +    for a failure is that it's recognized as an `x` and that it's associated
     +    with the color red -- the color of course is problematic for people who
     +    are red-green color-blind, but that's why they are paired with distinct
     +    shapes.
      
          Signed-off-by: Josh Soref <jsoref@gmail.com>
      
       ## Documentation/SubmittingPatches ##
     -@@ Documentation/SubmittingPatches: branches here: `https://github.com/<Your GitHub handle>/git/actions/workflows/ma
     - If a branch did not pass all test cases then it is marked with a red
     - +x+. In that case you can click on the failing job and navigate to
     - "ci/run-build-and-tests.sh" and/or "ci/print-test-failures.sh". You
     +@@ Documentation/SubmittingPatches: After the initial setup, CI will run whenever you push new changes
     + to your fork of Git on GitHub.  You can monitor the test state of all your
     + branches here: `https://github.com/<Your GitHub handle>/git/actions/workflows/main.yml`
     + 
     +-If a branch did not pass all test cases then it is marked with a red
     +-cross. In that case you can click on the failing job and navigate to
     +-"ci/run-build-and-tests.sh" and/or "ci/print-test-failures.sh". You
      -can also download "Artifacts" which are tarred (or zipped) archives
     -+can also download "Artifacts" which are zip archives containing
     -+tarred (or zipped) archives
     - with test data relevant for debugging.
     +-with test data relevant for debugging.
     ++If a branch does not pass all test cases then it will be marked with a
     ++red +x+, instead of a green check. In that case, you can click on the
     ++failing job and navigate to "ci/run-build-and-tests.sh" and/or
     ++"ci/print-test-failures.sh". You can also download "Artifacts" which
     ++are tarred (or zipped) archives with test data relevant for debugging.
       
       Then fix the problem and push your fix to your GitHub fork. This will
     + trigger a new CI build to ensure all tests pass.
  -:  ----------- >  8:  deb1bf02f3a SubmittingPatches: clarify GitHub artifact format
  9:  a4878f58fe4 =  9:  b1b75cc6a3e SubmittingPatches: hyphenate non-ASCII

-- 
gitgitgadget