From 4ed5562925539ef76b6e4b2002b98a8e734cf223 Mon Sep 17 00:00:00 2001 From: Emily Shaffer Date: Thu, 31 Oct 2019 14:03:36 -0700 Subject: myfirstcontrib: add 'psuh' to command-list.txt MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Signed-off-by: Emily Shaffer Signed-off-by: Junio C Hamano --- Documentation/MyFirstContribution.txt | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) (limited to 'Documentation/MyFirstContribution.txt') diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index 5e9b808f5f..12b7256454 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -534,6 +534,28 @@ you want to pass as a parameter something which would usually be interpreted as a flag.) `parse_options()` will terminate parsing when it reaches `--` and give you the rest of the options afterwards, untouched. +Now that you have a usage hint, you can teach Git how to show it in the general +command list shown by `git help git` or `git help -a`, which is generated from +`command-list.txt`. Find the line for 'git-pull' so you can add your 'git-psuh' +line above it in alphabetical order. Now, we can add some attributes about the +command which impacts where it shows up in the aforementioned help commands. The +top of `command-list.txt` shares some information about what each attribute +means; in those help pages, the commands are sorted according to these +attributes. `git psuh` is user-facing, or porcelain - so we will mark it as +"mainporcelain". For "mainporcelain" commands, the comments at the top of +`command-list.txt` indicate we can also optionally add an attribute from another +list; since `git psuh` shows some information about the user's workspace but +doesn't modify anything, let's mark it as "info". Make sure to keep your +attributes in the same style as the rest of `command-list.txt` using spaces to +align and delineate them: + +---- +git-prune-packed plumbingmanipulators +git-psuh mainporcelain info +git-pull mainporcelain remote +git-push mainporcelain remote +---- + Build again. Now, when you run with `-h`, you should see your usage printed and your command terminated before anything else interesting happens. Great! -- cgit v1.2.3 From 3ada78de3f8dbe2b0a2b67cade25d29a86f734c3 Mon Sep 17 00:00:00 2001 From: Emily Shaffer Date: Thu, 31 Oct 2019 14:03:37 -0700 Subject: myfirstcontrib: add dependency installation step 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 Signed-off-by: Emily Shaffer Signed-off-by: Junio C Hamano --- Documentation/MyFirstContribution.txt | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) (limited to 'Documentation/MyFirstContribution.txt') diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index 12b7256454..5ce94e077c 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -38,6 +38,26 @@ $ git clone https://github.com/git/git git $ cd git ---- +[[dependencies]] +=== Installing Dependencies + +To build Git from source, you need to have a handful of dependencies installed +on your system. For a hint of what's needed, you can take a look at +`INSTALL`, paying close attention to the section about Git's dependencies on +external programs and libraries. That document mentions a way to "test-drive" +our freshly built Git without installing; that's the method we'll be using in +this tutorial. + +Make sure that your environment has everything you need by building your brand +new clone of Git from the above step: + +---- +$ make +---- + +NOTE: The Git build is parallelizable. `-j#` is not included above but you can +use it as you prefer, here and elsewhere. + [[identify-problem]] === Identify Problem to Solve @@ -138,9 +158,6 @@ NOTE: When you are developing the Git project, it's preferred that you use the `DEVELOPER` flag; if there's some reason it doesn't work for you, you can turn it off, but it's a good idea to mention the problem to the mailing list. -NOTE: The Git build is parallelizable. `-j#` is not included above but you can -use it as you prefer, here and elsewhere. - Great, now your new command builds happily on its own. But nobody invokes it. Let's change that. -- cgit v1.2.3 From 3c8d754c4b7123e57febdcf95330a073c8eeec7e Mon Sep 17 00:00:00 2001 From: Emily Shaffer Date: Thu, 31 Oct 2019 14:03:38 -0700 Subject: myfirstcontrib: hint to find gitgitgadget allower 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 Signed-off-by: Junio C Hamano --- Documentation/MyFirstContribution.txt | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'Documentation/MyFirstContribution.txt') diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index 5ce94e077c..b55837e646 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -785,6 +785,14 @@ will automatically run your PRs through the CI even without the permission given but you will not be able to `/submit` your changes until someone allows you to use the tool. +NOTE: You can typically find someone who can `/allow` you on GitGitGadget by +either examining recent pull requests where someone has been granted `/allow` +(https://github.com/gitgitgadget/git/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aopen+%22%2Fallow%22[Search: +is:pr is:open "/allow"]), in which case both the author and the person who +granted the `/allow` can now `/allow` you, or by inquiring on the +https://webchat.freenode.net/#git-devel[#git-devel] IRC channel on Freenode +linking your pull request and asking for someone to `/allow` you. + If the CI fails, you can update your changes with `git rebase -i` and push your branch again: -- cgit v1.2.3 From 46c67492aa3ab2779f9322790ca8fffcd5bfaa80 Mon Sep 17 00:00:00 2001 From: Jeff King Date: Wed, 27 Nov 2019 07:53:43 -0500 Subject: doc: recommend lore.kernel.org over public-inbox.org 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 Acked-by: Eric Wong Signed-off-by: Junio C Hamano --- Documentation/MyFirstContribution.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/MyFirstContribution.txt') diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index f8670379c0..d7163075ca 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -970,7 +970,7 @@ reviewers the changes you've made that may not be as visible. You will also need to go and find the Message-Id of your previous cover letter. You can either note it when you send the first series, from the output of `git send-email`, or you can look it up on the -https://public-inbox.org/git[mailing list]. Find your cover letter in the +https://lore.kernel.org/git[mailing list]. Find your cover letter in the archives, click on it, then click "permalink" or "raw" to reveal the Message-Id header. It should match: -- cgit v1.2.3