summaryrefslogtreecommitdiff
path: root/Documentation/MyFirstContribution.txt
AgeCommit message (Collapse)AuthorFilesLines
2021-09-22MyFirstContribution: Document --range-diff option when writing v2Libravatar Glen Choo1-11/+31
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 <chooglen@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-06-09MyFirstContribution: link #git-devel to Libera ChatLibravatar Atharva Raykar1-2/+2
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 <raykar.ath@gmail.com> Reviewed-by: Emily Shaffer <emilyshaffer@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-01-21tests: remove support for GIT_TEST_GETTEXT_POISONLibravatar Ævar Arnfjörð Bjarmason1-1/+1
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 <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-11-30Merge branch 'jc/do-not-just-explain-but-update-your-patch'Libravatar Junio C Hamano1-1/+15
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
2020-11-24MyFirstContribition: answering questions is not the end of the storyLibravatar Junio C Hamano1-1/+15
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 <emilyshaffer@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-11-02Merge branch 'es/tutorial-mention-asciidoc-early'Libravatar Junio C Hamano1-2/+3
Doc update. * es/tutorial-mention-asciidoc-early: MyFirstContribution: clarify asciidoc dependency
2020-10-20Documentation: stylistically normalize references to Signed-off-by:Libravatar Bradley M. Kuhn1-1/+1
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 <xmqqy2k1dfoh.fsf@gitster.c.googlers.com> 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" <tytso@mit.edu> Signed-off-by: Bradley M. Kuhn <bkuhn@sfconservancy.org> Acked-by: Taylor Blau <me@ttaylorr.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-10-16MyFirstContribution: clarify asciidoc dependencyLibravatar Emily Shaffer1-2/+3
Per IRC: [19:52] <lkmandy> 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 <emilyshaffer@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-08-17config: drop git_config_get_string_const()Libravatar Jeff King1-2/+2
As evidenced by the leak fixes in the previous commit, the "const" in git_config_get_string_const() clearly misleads people into thinking that it does not allocate a copy of the string. We can fix this by renaming it, but it's easier still to just drop it. Of the four remaining callers: - The one in git_config_parse_expiry() still needs to allocate, since that's what its callers expect. We can just use the non-const version and cast our pointer. Slightly ugly, but the damage is contained in one spot. - The two in apply are writing to global "const char *" variables, and need to continue allocating. We often mark these as const because we assign default string literals to them. But in this case we don't do that, so we can just declare them as real "char *" pointers and use the non-const version. - The call in checkout doesn't actually need a copy; it can just use the non-allocating "tmp" version of the function. The function is also mentioned in the MyFirstContribution document. We can swap that call out for the non-allocating "tmp" variant, which fits well in the example given. We'll drop the "configset" and "repo" variants, as well (which are unused). Note that this frees up the "const" name, so we could rename the "tmp" variant back to that. But let's give some time for topics in flight to adapt to the new code before doing so (if we do it too soon, the function semantics will change but the compiler won't alert us). Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-06-25docs: adjust for the recent rename of `pu` to `seen`Libravatar Johannes Schindelin1-2/+2
As of "What's cooking in git.git (Jun 2020, #04; Mon, 22)", there is no longer any `pu` branch, but a `seen` branch. While we technically do not even need to update the manual pages, it makes sense to update them because they clearly talk about branches in git.git. Please note that in two instances, this patch not only updates the branch name, but also the description "(proposed updates)". Where appropriate, quotes have been added for readability. Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-02-14MyFirstContribution: rephrase contact infoLibravatar Emily Shaffer1-13/+16
Make an effort not to discourage new users from mailing questions to git@vger.kernel.org, and explain the purpose of the mentoring list in contrast to the main list. Signed-off-by: Emily Shaffer <emilyshaffer@google.com> Reviewed-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-01-24MyFirstContribution: add avenues for getting helpLibravatar Emily Shaffer1-0/+33
With https://lore.kernel.org/git/20191114194708.GD60198@google.com/ we now have a mentoring mailing list, to which we should direct new contributors who have questions. Mention #git-devel, which is targeted for Git contributors; asking for help with getting a first contribution together is on-topic for that channel. Also mention some of the conventions in case folks are unfamiliar with IRC. Because the mentoring list and #git-devel are both a subset of Git contributors, finally list the main Git list and mention some of the posting conventions. Signed-off-by: Emily Shaffer <emilyshaffer@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-12-06Merge branch 'jk/lore-is-the-archive'Libravatar Junio C Hamano1-1/+1
Doc update for the mailing list archiving and nntp service. * jk/lore-is-the-archive: doc: replace public-inbox links with lore.kernel.org doc: recommend lore.kernel.org over public-inbox.org
2019-11-30doc: recommend lore.kernel.org over public-inbox.orgLibravatar Jeff King1-1/+1
Since lore.kernel.org now has the same archive as public-inbox.org and may have more longevity going forward[1], let's recommend people use it for finding or referencing messages. [1] https://public-inbox.org/git/20191120195556.GA25189@dcvr/ or if you like: https://lore.kernel.org/git/20191120195556.GA25189@dcvr/ Signed-off-by: Jeff King <peff@peff.net> Acked-by: Eric Wong <e@80x24.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-11-02myfirstcontrib: hint to find gitgitgadget allowerLibravatar Emily Shaffer1-0/+8
GitGitGadget, a handy tool for converting pull requests against Git into Git-mailing-list-friendly-patch-emails, requires as anti-spam that all new users be "/allow"ed by an existing user once before it will do anything for that new user. While this tutorial explained that mechanism, it did not give much hint on how to go about finding someone to allow your new pull request. So, teach our new GitGitGadget user where to look for someone who can add their name to the list. The advice in this patch is based on the advice proposed for GitGitGadget: https://github.com/gitgitgadget/gitgitgadget/pull/138 Signed-off-by: Emily Shaffer <emilyshaffer@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-11-02myfirstcontrib: add dependency installation stepLibravatar Emily Shaffer1-3/+20
Indicate that the user needs some dependencies before the build will run happily on their machine; this dependency list doesn't seem to be made clear anywhere else in the project documentation. Then, so the user can be certain any build failures are due to their code and not their environment, perform a build on a clean checkout of 'master'. Also, move the note about build parallelization up here, so that it appears next to the very first build invocation in the tutorial. Reported-by: Heba Waly <heba.waly@gmail.com> Signed-off-by: Emily Shaffer <emilyshaffer@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-11-02myfirstcontrib: add 'psuh' to command-list.txtLibravatar Emily Shaffer1-0/+22
Users can discover commands and their brief usage by running 'git help git' or 'git help -a'; both of these pages list all available commands based on the contents of 'command-list.txt'. That means adding a new command there is an important part of the new command process, and therefore belongs in the new command tutorial. Teach new users how to add their command, and include a brief overview of how to discover which attributes to place on the command in the list. Since 'git psuh' prints some workspace info, doesn't modify anything, and is targeted as a user-facing porcelain command, list it as a 'mainporcelain' and 'info' command. As the usage string is required to generate this documentation, don't add the command to the list until after the usage string is added to the tutorial. Reported-by: SZEDER Gábor <szeder.dev@gmail.com> Signed-off-by: Emily Shaffer <emilyshaffer@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-09-28doc: MyFirstContribution: fix cmd placement instructionsLibravatar Pedro Sousa1-5/+5
Using the pull command instead of push is more accurate when giving instructions on placing the psuh command in alphabetical order. Signed-off-by: Pedro Sousa <pedroteosousa@gmail.com> Acked-by: Philip Oakley <philipoakley@iee.email> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-06-24doc: improve usage string in MyFirstContributionLibravatar Christian Couder1-5/+7
We implement a command called git-psuh which accept arguments, so let's show that it accepts arguments in the doc and the usage string. While at it, we need to prepare "a NULL-terminated array of usage strings", not just "a NULL-terminated usage string". Helped-by: Emily Shaffer <emilyshaffer@google.com> Helped-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Christian Couder <chriscool@tuxfamily.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-05-29doc: add some nit fixes to MyFirstContributionLibravatar Emily Shaffer1-4/+27
A trial run-through of the tutorial revealed a few typos and missing commands in the tutorial itself. This commit fixes typos, clarifies which lines to keep or modify in some places, and adds a section on putting the git-psuh binary into the gitignore. Signed-off-by: Emily Shaffer <emilyshaffer@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-05-19documentation: add anchors to MyFirstContributionLibravatar Emily Shaffer1-0/+35
During the course of review for MyFirstContribution.txt, the suggestion came up to include anchors to make it easier for veteran contributors to link specific sections of this documents to newbies. To make life easier for reviewers, add these anchors in their own commit. See review context here: https://public-inbox.org/git/20190507195938.GD220818@google.com/ AsciiDoc does not support :sectanchors: and the anchors are not discoverable, but they are referenceable. So a link to "foo.com/MyFirstContribution.html#prerequisites" will still work if that file was generated with AsciiDoc. The inclusion of :sectanchors: does not create warnings or errors while compiling directly with `asciidoc -b html5 Documentation/MyFirstContribution.txt` or while compiling with `make doc`. AsciiDoctor does support :sectanchors: and displays a paragraph link on mouseover. When the anchor is included above or inline with a section (as in this change), the link provided points to the custom ID contained within [[]] instead of to an autogenerated ID. Practically speaking, this means we have .../MyFirstContribution.html#summary instead of .../MyFirstContribution.html#_summary. In addition to being prettier, the custom IDs also enable anchor linking to work with asciidoc-generated pages. This change compiles with no warnings using `asciidoctor -b html5 Documentation/MyFirstContribution.txt`. Signed-off-by: Emily Shaffer <emilyshaffer@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-05-19documentation: add tutorial for first contributionLibravatar Emily Shaffer1-0/+1074
This tutorial covers how to add a new command to Git and, in the process, everything from cloning git/git to getting reviewed on the mailing list. It's meant for new contributors to go through interactively, learning the techniques generally used by the git/git development community. Reviewed-by: Johannes Schindelin <johannes.schindelin@gmx.de> Reviewed-by: Jonathan Tan <jonathantanmy@google.com> Signed-off-by: Emily Shaffer <emilyshaffer@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>