git/Documentation/SubmittingPatches, branch v2.45.2

SubmittingPatches: release-notes entry experiment

2024-03-26T16:37:15Z

The "What's cooking" report lists the topics in flight, with a short paragraph descibing what they are about. Once written, the description is automatically picked up from the "What's cooking" report and used in the commit log message of the merge commit when the topic is merged into integration branches. These commit log messges of the merge commits are then propagated to the release notes. It has been the maintainer's task to prepare these entries in the "What's cooking" report. Even though the original author of a topic may be in the best position to write the initial description of a topic, we so far lacked a formal channel for the author to suggest what description to use. The usual procedure has been for the author to see the topic described in "What's cooking" report, and then either complain about inaccurate explanation and/or offer a rewrite. Let's try an experiment to optionally let the author propose the one paragraph description when the topic is submitted. Pick the cover letter as the logical place to do so, and describe an experimental workflow in the SubmittingPatches document. Signed-off-by: Junio C Hamano

SubmittingPatches: hyphenate non-ASCII

2023-12-28T05:33:24Z

Git documentation does this with the exception of ancient release notes. Signed-off-by: Josh Soref Signed-off-by: Junio C Hamano

SubmittingPatches: clarify GitHub artifact format

2023-12-28T05:33:24Z

GitHub wraps artifacts generated by workflows in a .zip file. 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 Signed-off-by: Josh Soref Signed-off-by: Junio C Hamano

SubmittingPatches: clarify GitHub visual

2023-12-28T05:33:24Z

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). 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 Signed-off-by: Junio C Hamano

SubmittingPatches: provide tag naming advice

2023-12-28T05:33:23Z

Current statistics show a strong preference to only capitalize the first letter in a hyphenated tag, but that some guidance would be helpful: git log | perl -ne 'next unless /^\s+(?:Signed-[oO]ff|Acked)-[bB]y:/; s/^\s+//;s/:.*/:/;print'| sort|uniq -c|sort -n 2 Signed-off-By: 4 Signed-Off-by: 22 Acked-By: 47 Signed-Off-By: 2202 Acked-by: 95315 Signed-off-by: Signed-off-by: Josh Soref Signed-off-by: Junio C Hamano

SubmittingPatches: update extra tags list

2023-12-28T05:33:23Z

Add items with at least 100 uses in the past three years: - Co-authored-by - Helped-by - Mentored-by - Suggested-by git log --since=3.years| perl -ne 'next unless /^\s+[A-Z][a-z]+-\S+:/;s/^\s+//;s/:.*/:/;print'| sort|uniq -c|sort -n|grep '[0-9][0-9] ' 14 Based-on-patch-by: 14 Original-patch-by: 17 Tested-by: 100 Suggested-by: 121 Co-authored-by: 163 Mentored-by: 274 Reported-by: 290 Acked-by: 450 Helped-by: 602 Reviewed-by: 14111 Signed-off-by: Signed-off-by: Josh Soref Signed-off-by: Junio C Hamano

SubmittingPatches: discourage new trailers

2023-12-28T05:33:23Z

There seems to be consensus amongst the core Git community on a working set of common trailers, and there are non-trivial costs to people inventing new trailers (research to discover what they mean/how they differ from existing trailers) such that inventing new ones is generally unwarranted and not something to be recommended to new contributors. Suggested-by: Elijah Newren Signed-off-by: Josh Soref Signed-off-by: Junio C Hamano

SubmittingPatches: drop ref to "What's in git.git"

2023-12-28T05:33:23Z

"What's in git.git" was last seen in 2010: https://lore.kernel.org/git/?q=%22what%27s+in+git.git%22 https://lore.kernel.org/git/7vaavikg72.fsf@alter.siamese.dyndns.org/ Signed-off-by: Josh Soref Signed-off-by: Junio C Hamano

Merge branch 'ar/submitting-patches-doc-update'

2023-11-07T01:26:42Z

Doc update. * ar/submitting-patches-doc-update: SubmittingPatches: call gitk's command "Copy commit reference"

Merge branch 'sn/typo-grammo-phraso-fixes'

2023-10-29T22:09:55Z

Many typos, ungrammatical sentences and wrong phrasing have been fixed. * sn/typo-grammo-phraso-fixes: t/README: fix multi-prerequisite example doc/gitk: s/sticked/stuck/ git-jump: admit to passing merge mode args to ls-files doc/diff-options: improve wording of the log.diffMerges mention doc: fix some typos, grammar and wording issues