git/Documentation/MyFirstContribution.txt, branch v2.35.2

Merge branch 'jc/tutorial-format-patch-base'

2021-11-29T23:41:46Z

Teach and encourage first-time contributors to this project to state the base commit when they submit their topic. * jc/tutorial-format-patch-base: MyFirstContribution: teach to use "format-patch --base=auto"

MyFirstContribution: teach to use "format-patch --base=auto"

2021-10-23T21:03:11Z

Let's encourage first-time contributors to tell us what commit they based their work on with the format-patch invocation. As the example already forks from origin/master and branch.autosetupmerge by default records the upstream when the psuh branch was created, we can use --base=auto for this. Also, mention that the range of commits can simply be given with `@{u}` if they are on the `psuh` branch already. As we are getting one more option on the command line, and spending one paragraph each to explain them, let's reformat that part of the description as a bulleted list. Helped-by: Bagas Sanjaya Signed-off-by: Junio C Hamano

MyFirstContribution: Document --range-diff option when writing v2

2021-09-22T21:25:05Z

In the "Sending v2" section, readers are directed to create v2 patches without using --range-diff. However, it is customary to include a range-diff against the v1 patches as a reviewer aid. Update the "Sending v2" section to suggest a simple workflow that uses the --range-diff option. Also include some explanation for -v2 and --range-diff to help the reader understand the importance. Signed-off-by: Glen Choo Signed-off-by: Junio C Hamano

MyFirstContribution: link #git-devel to Libera Chat

2021-06-09T00:22:54Z

Many of the regulars on #git-devel are now on Libera Chat, to the extent that the community page now lists it as the IRC Channel[1]. This will help new contributors find the right place, if they choose to ask questions on `#git-devel`. Relevant discussion on the IRC transition: https://lore.kernel.org/git/CAJoAoZ=e62sceNpcR5L5zjsj177uczTnXjcAg+BbOoOkeH8vXQ@mail.gmail.com/ [1] https://git-scm.com/community Signed-off-by: Atharva Raykar Reviewed-by: Emily Shaffer Signed-off-by: Junio C Hamano

tests: remove support for GIT_TEST_GETTEXT_POISON

2021-01-21T23:50:01Z

This removes the ability to inject "poison" gettext() messages via the GIT_TEST_GETTEXT_POISON special test setup. I initially added this as a compile-time option in bb946bba761 (i18n: add GETTEXT_POISON to simulate unfriendly translator, 2011-02-22), and most recently modified to be toggleable at runtime in 6cdccfce1e0 (i18n: make GETTEXT_POISON a runtime option, 2018-11-08).. The reason for its removal is that the trade-off of maintaining it v.s. what it's getting us has long since flipped. When gettext was integrated in 5e9637c6297 (i18n: add infrastructure for translating Git with gettext, 2011-11-18) there was understandable concern on the Git ML that in marking messages for translation en-masse we'd inadvertently mark plumbing messages. The GETTEXT_POISON facility was a way to smoke those out via our test suite. Nowadays however we're done (or almost entirely done) with any marking of messages for translation. New messages are usually marked by their authors, who'll know whether it makes sense to translate them or not. If not any errors in marking the messages are much more likely to be spotted in review than in the the initial deluge of i18n patches in the 2011-2012 era. So let's just remove this. This leaves the test suite in a state where we still have a lot of test_i18n, C_LOCALE_OUTPUT etc. uses. Subsequent commits will remove those too. The change to t/lib-rebase.sh is a selective revert of the relevant part of f2d17068fd (i18n: rebase-interactive: mark comments of squash for translation, 2016-06-17), and the comment in t/t3406-rebase-message.sh is from c7108bf9ed (i18n: rebase: mark messages for translation, 2012-07-25). Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano

Merge branch 'jc/do-not-just-explain-but-update-your-patch'

2020-11-30T22:49:43Z

Expectation for the original contributor after responding to a review comment to use the explanation in a patch update has been described. * jc/do-not-just-explain-but-update-your-patch: MyFirstContribition: answering questions is not the end of the story

MyFirstContribition: answering questions is not the end of the story

2020-11-24T22:11:17Z

A review exchange may begin with a reviewer asking "what did you mean by this phrase in your log message (or here in the doc)?", the author answering what was meant, and then the reviewer saying "ah, that is what you meant---then the flow of the logic makes sense". But that is not the happy end of the story. New contributors often forget that the material that has been reviewed in the above exchange is still unclear in the same way to the next person who reads it, until it gets updated. While we are in the vicinity, rephrase the verb "request" used to refer to comments by reviewers to "suggest"---this matches the contrast between "original" and "suggested" that appears later in the same paragraph, and more importantly makes it clearer that it is not like authors are to please reviewers' wishes but rather reviewers are merely helping authors to polish their commits. Reviewed-by: Emily Shaffer Signed-off-by: Junio C Hamano

Merge branch 'es/tutorial-mention-asciidoc-early'

2020-11-02T21:17:47Z

Doc update. * es/tutorial-mention-asciidoc-early: MyFirstContribution: clarify asciidoc dependency

Documentation: stylistically normalize references to Signed-off-by:

2020-10-20T18:57:40Z

Ted reported an old typo in the git-commit.txt and merge-options.txt. Namely, the phrase "Signed-off-by line" was used without either a definite nor indefinite article. Upon examination, it seems that the documentation (including items in Documentation/, but also option help strings) have been quite inconsistent on usage when referring to `Signed-off-by`. First, very few places used a definite or indefinite article with the phrase "Signed-off-by line", but that was the initial typo that led to this investigation. So, normalize using either an indefinite or definite article consistently. The original phrasing, in Commit 3f971fc425b (Documentation updates, 2005-08-14), is "Add Signed-off-by line". Commit 6f855371a53 (Add --signoff, --check, and long option-names. 2005-12-09) switched to using "Add `Signed-off-by:` line", but didn't normalize the former commit to match. Later commits seem to have cut and pasted from one or the other, which is likely how the usage became so inconsistent. Junio stated on the git mailing list in a preference to leave off the colon. Thus, prefer `Signed-off-by` (with backticks) for the documentation files and Signed-off-by (without backticks) for option help strings. Additionally, Junio argued that "trailer" is now the standard term to refer to `Signed-off-by`, saying that "becomes plenty clear that we are not talking about any random line in the log message". As such, prefer "trailer" over "line" anywhere the former word fits. However, leave alone those few places in documentation that use Signed-off-by to refer to the process (rather than the specific trailer), or in places where mail headers are generally discussed in comparison with Signed-off-by. Reported-by: "Theodore Y. Ts'o" Signed-off-by: Bradley M. Kuhn Acked-by: Taylor Blau Signed-off-by: Junio C Hamano

MyFirstContribution: clarify asciidoc dependency

2020-10-16T22:13:11Z

Per IRC: [19:52] With respect to the MyFirstContribution tutorial, I will like to suggest this - Under the section "Adding Documentation", just before the "make all doc" command, it will be really helpful to prompt a user to check if they have the asciidoc package installed, if they don't, the command should be provided or they can just be pointed to install it So, let's move the note about the dependency to before the build command blockquote. Signed-off-by: Emily Shaffer Signed-off-by: Junio C Hamano