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@xxxxxxxxx> ## 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@xxxxxxxxx> ## 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@xxxxxxxxx> ## 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
