doc:clarify which remotes can be used when contributing
PATCH 1/1 doc:clarify which remotes can be used when contributing
From: Daniele Sassoli <[email protected]>
The docs mostly point to using git/git as one's remote, however, when it comes to Sending a PR to GitGitGadget section, the reader is told to use gitgitgadget/git, with no mention of git/git, potentially leading to some confusion.
Clarify that both gitgitgadget/git and git/git can be used, albeit with some differences.
---
doc:clarify which remotes can be used when contributing
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2034%2FDanieleSassoli%2Fclarify-remote-to-use-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2034/DanieleSassoli/clarify-remote-to-use-v1
Pull-Request: https://github.com/git/git/pull/2034
Documentation/MyFirstContribution.adoc | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-)
Documentation/MyFirstContribution.adoc +7 -1
@@ -908,10 +908,16 @@ Now you should be able to go and check out your newly created branch on GitHub. === Sending a PR to GitGitGadget In order to have your code tested and formatted for review, you need to start by -opening a Pull Request against `gitgitgadget/git`. Head to +opening a Pull Request against either `gitgitgadget/git` or `git/git`, depending +on which mirror you initially cloned from. Head to https://github.com/gitgitgadget/git and open a PR either with the "New pull request" button or the convenient "Compare & pull request" button that may appear with the name of your newly pushed branch. +If you're using https://github.com/git/git as your remote, you will need to +open the pull-request from your fork, selecting `git/git` as base. + +The differences between using `gitgitgadget/git` and `git/git` as your base can +be found [here](https://gitgitgadget.github.io/#should-i-use-gitgitgadget-on-gitgitgadgets-git-fork-or-on-gits-github-mirror) Review the PR's title and description, as they're used by GitGitGadget respectively as the subject and body of the cover letter for your change. Refer
base-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0
Signature · 1 line
gitgitgadget
Documentation/MyFirstContribution.adoc Now you should be able to go and check out your newly created branch on GitHub. · line 920
Quoted 8 lines · Daniele Sassoli via GitGitGadget
https://github.com/gitgitgadget/git and open a PR either with the "New pull request" button or the convenient "Compare & pull request" button that may appear with the name of your newly pushed branch.
Documentation/MyFirstContribution.adoc +5
-0+If you're using https://github.com/git/git as your remote, you will need to +open the pull-request from your fork, selecting `git/git` as base. + +The differences between using `gitgitgadget/git` and `git/git` as your base can +be found [here](https://gitgitgadget.github.io/#should-i-use-gitgitgadget-on-gitgitgadgets-git-fork-or-on-gits-github-mirror)
Looking at the table, there is no advantage to use git/git at all.
Instead of telling them that they can use either (with reduced capabilities if you pick one of them instead of the other), wouldn't it be easier for the user if this section taught them how to switch their fork that they originally created out of git/git to be based on gitgitgadget/git instead? Something along the lines of
... If you originally forked from https://github.com/git/git/,
you can easily correct it by running (you only need to do this once):
$ git remote set-url origin https://github.com/gitgitgadget/git/
$ git fetch --prune origin
A pull request at https://github.com/gitgitgadget/git/ can be opened once you do so.
but you'd need to validate the procedure, as I didn't try it myself.
Thanks.
Quoted 11 lines · Junio C Hamano
Documentation/MyFirstContribution.adoc Now you should be able to go and check out your newly created branch on GitHub. · line 920
Quoted 8 lines · Daniele Sassoli via GitGitGadget
https://github.com/gitgitgadget/git and open a PR either with the "New pull request" button or the convenient "Compare & pull request" button that may appear with the name of your newly pushed branch.
Documentation/MyFirstContribution.adoc +5
-0+If you're using https://github.com/git/git as your remote, you will need to +open the pull-request from your fork, selecting `git/git` as base. + +The differences between using `gitgitgadget/git` and `git/git` as your base can +be found [here](https://gitgitgadget.github.io/#should-i-use-gitgitgadget-on-gitgitgadgets-git-fork-or-on-gits-github-mirror)Looking at the table, there is no advantage to use git/git at all.
Quoted 4 lines
Instead of telling them that they can use either (with reduced capabilities if you pick one of them instead of the other), wouldn't it be easier for the user if this section taught them how to switch their fork that they originally created out of git/git to be based
Most of the document, including the "Getting Started" section, points to cloning from git/git. It's only when it comes to the gitgitgadget section that we mention gitgitgadget/git.
It's true that there are no advantages of using git/git over gitgitgadget/git, but I would argue that the disadvantages are quite minor and definitely don't impact someone at their first contribution?
As we've told the reader so far to use git/git, I don't see why we should tell him to change his remote for potentially no benefit. If we're saying that gitgitgadget should be used only on gitgitgadget/git, then we should restructure the document to point to that from the beginning, no?
PS. please note it's my first time replying on the mailing list directly, apologies if I did something wrong, like wrong posting style or wrong people in cc.
Quoted 15 lines
on gitgitgadget/git instead? Something along the lines of
... If you originally forked from https://github.com/git/git/,
you can easily correct it by running (you only need to do this once):$ git remote set-url origin https://github.com/gitgitgadget/git/
$ git fetch --prune originA pull request at https://github.com/gitgitgadget/git/ can be opened once you do so.
but you'd need to validate the procedure, as I didn't try it myself.
Thanks.
Quoted 12 lines · Daniele Sassoli
Quoted 10 lines · Junio C Hamano
Documentation/MyFirstContribution.adoc Now you should be able to go and check out your newly created branch on GitHub. · line 920
Quoted 8 lines · Daniele Sassoli via GitGitGadget
https://github.com/gitgitgadget/git and open a PR either with the "New pull request" button or the convenient "Compare & pull request" button that may appear with the name of your newly pushed branch.
Documentation/MyFirstContribution.adoc +5
-0+If you're using https://github.com/git/git as your remote, you will need to +open the pull-request from your fork, selecting `git/git` as base. + +The differences between using `gitgitgadget/git` and `git/git` as your base can +be found [here](https://gitgitgadget.github.io/#should-i-use-gitgitgadget-on-gitgitgadgets-git-fork-or-on-gits-github-mirror)Looking at the table, there is no advantage to use git/git at all.
Quoted 7 lines
Most of the document, including the "Getting Started" section, points to cloning from git/git. It's only when it comes to the gitgitgadget section that we mention gitgitgadget/git.
It's true that there are no advantages of using git/git over gitgitgadget/git, but I would argue that the disadvantages are quite minor and definitely don't impact someone at their first contribution?
Even the disabled things may be rather advanced features, wouldn't it still impact them for them to stay to be on git/git?
Those started from git/git have to learn what different things they need to do to use GGG by reading this extra piece of documentation, and then if they plan to keep using GGG, they will have to do this extra thing each and every time until the end of time (since your preference is not to teach switching to GGG/git from git/git).
I have no strong opinions as I wouldn't be the one who is doing something extra every time, but I'd rather see our new contributors having to spend less time to get their work published and more time to polish their work into reviewable state.
Quoted 13 lines · Junio C Hamano
Quoted 11 lines · Daniele Sassoli
Quoted 10 lines · Junio C Hamano
Documentation/MyFirstContribution.adoc Now you should be able to go and check out your newly created branch on GitHub. · line 920
Quoted 8 lines · Daniele Sassoli via GitGitGadget
https://github.com/gitgitgadget/git and open a PR either with the "New pull request" button or the convenient "Compare & pull request" button that may appear with the name of your newly pushed branch.
Documentation/MyFirstContribution.adoc +5
-0+If you're using https://github.com/git/git as your remote, you will need to +open the pull-request from your fork, selecting `git/git` as base. + +The differences between using `gitgitgadget/git` and `git/git` as your base can +be found [here](https://gitgitgadget.github.io/#should-i-use-gitgitgadget-on-gitgitgadgets-git-fork-or-on-gits-github-mirror)Looking at the table, there is no advantage to use git/git at all.
Quoted 7 lines
Quoted 7 lines
Most of the document, including the "Getting Started" section, points to cloning from git/git. It's only when it comes to the gitgitgadget section that we mention gitgitgadget/git.
It's true that there are no advantages of using git/git over gitgitgadget/git, but I would argue that the disadvantages are quite minor and definitely don't impact someone at their first contribution?
First of all, thanks for taking the time to review this series, really appreciate it.
Quoted 8 lines
Even the disabled things may be rather advanced features, wouldn't it still impact them for them to stay to be on git/git?
Those started from git/git have to learn what different things they need to do to use GGG by reading this extra piece of documentation, and then if they plan to keep using GGG, they will have to do this extra thing each and every time until the end of time (since your preference is not to teach switching to GGG/git from git/git).
I think for someone's first contribution, the most straightforward thing to do is simply to stick with what they have setup so far. If someone finds themselves doing this more than once, I would imagine they know what they're doing and are not beginners, so can figure out to switch the remote themselves.
Quoted 5 lines
I have no strong opinions as I wouldn't be the one who is doing something extra every time, but I'd rather see our new contributors having to spend less time to get their work published and more time to polish their work into reviewable state.
We're trying to achieve the same outcome, which is why I'm trying to have the reader follow the path of least resistance in getting their patch to the mailing list. If they then find themselves contributing regularly and realise they need the more advanced features of gitgitgadget on a regular basis, I'm sure they'll figure to switch the remote themselves.
Quoted 1 line
Quoted 1 line · Daniele Sassoli
Subject: Re: [PATCH] doc:clarify which remotes can be used when contributing
A space is missing before "clarify".
Quoted 6 lines
Quoted 5 lines
Those started from git/git have to learn what different things they need to do to use GGG by reading this extra piece of documentation, and then if they plan to keep using GGG, they will have to do this extra thing each and every time until the end of time (since your preference is not to teach switching to GGG/git from git/git).
Quoted 10 lines
I think for someone's first contribution, the most straightforward thing to do is simply to stick with what they have setup so far. If someone finds themselves doing this more than once, I would imagine they know what they're doing and are not beginners, so can figure out to switch the remote themselves.
...
We're trying to achieve the same outcome, which is why I'm trying to have the reader follow the path of least resistance in getting their patch to the mailing list. If they then find themselves contributing regularly and realise they need the more advanced features of gitgitgadget on a regular basis, I'm sure they'll figure to switch the remote themselves.
Having been in this project for longer than some people, I strongly suspect that "they'll figure to switch" will never happen. Even when a solution they have (e.g. "Here is how you work around to use GGG when you didn't start with GGG") is more cumbersome than it has to be, people tend to stay there in a local minimum, not necessarily out of habit and laziness, but because they are not told that there are better ways. When they do not know they need to "figure to switch", they won't.
Having said that, as I said, I do not have strong opinions, so I'll let other people to discuss and come to their own consensus ;-)
Thanks for writing a patch.
Quoted 27 lines · Daniele Sassoli via GitGitGadget
From: Daniele Sassoli <[email protected]>
The docs mostly point to using git/git as one's remote, however, when it comes to Sending a PR to GitGitGadget section, the reader is told to use gitgitgadget/git, with no mention of git/git, potentially leading to some confusion.
Clarify that both gitgitgadget/git and git/git can be used, albeit with some differences.
Signed-off-by Daniele Sassoli <[email protected]>---
doc:clarify which remotes can be used when contributingPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2034%2FDanieleSassoli%2Fclarify-remote-to-use-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2034/DanieleSassoli/clarify-remote-to-use-v1
Pull-Request: https://github.com/git/git/pull/2034Documentation/MyFirstContribution.adoc | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-)Documentation/MyFirstContribution.adoc +0
-0
Documentation/MyFirstContribution.adoc Now you should be able to go and check out your newly created branch on GitHub. · line 912
Quoted 6 lines
Documentation/MyFirstContribution.adoc +2
-1@@ -908,10 +908,16 @@ Now you should be able to go and check out your newly created branch on GitHub. === Sending a PR to GitGitGadget In order to have your code tested and formatted for review, you need to start by -opening a Pull Request against `gitgitgadget/git`. Head to +opening a Pull Request against either `gitgitgadget/git` or `git/git`, depending +on which mirror you initially cloned from. Head to
I think mentioning that opening a PR in either project is fine is helpful...especially since the UI sometimes changes the target to git/git when I wanted to open against gitgitgadget/git, and I don't notice and I open yet another PR in the wrong place. However, having it opened in the wrong place rarely makes any meaningful difference, so it would probably be helpful to let new users know that it's okay to open it in either place as you do here.
However, where you cloned from doesn't matter when you open the pull request, so I'd strike the ", depending on which mirror you initially cloned from." part of this change.
Documentation/MyFirstContribution.adoc Now you should be able to go and check out your newly created branch on GitHub. · line 917
Quoted 5 lines
Documentation/MyFirstContribution.adoc +2
-0https://github.com/gitgitgadget/git and open a PR either with the "New pull request" button or the convenient "Compare & pull request" button that may appear with the name of your newly pushed branch. +If you're using https://github.com/git/git as your remote, you will need to +open the pull-request from your fork, selecting `git/git` as base.
...and I think we should strike these two sentences as well, or at least reword them; your remote URL is immaterial.
(Not only have I opened up against both gitgitgadget/git and git/git in the past, my clone URL wasn't necessarily either one of these.)
Documentation/MyFirstContribution.adoc Now you should be able to go and check out your newly created branch on GitHub. · line 920
Quoted 3 lines
Documentation/MyFirstContribution.adoc +3
-0+ +The differences between using `gitgitgadget/git` and `git/git` as your base can +be found [here](https://gitgitgadget.github.io/#should-i-use-gitgitgadget-on-gitgitgadgets-git-fork-or-on-gits-github-mirror)
I like this call out.
Quoted 6 lines
Documentation/MyFirstContribution.adoc +0
-0Review the PR's title and description, as they're used by GitGitGadget respectively as the subject and body of the cover letter for your change. Referbase-commit:
c44beea485f0f2feaf460e2ac87fdd5608d63cf0--
gitgitgadget
Thanks for sending the patch in.
PATCH v2 1/1 doc:clarify which remotes can be used when contributing
In reply to Daniele Sassoli via GitGitGadgetFrom: Daniele Sassoli <[email protected]>
The docs mostly point to using git/git as one's remote, however, when it comes to Sending a PR to GitGitGadget section, the reader is told to use gitgitgadget/git, with no mention of git/git, potentially leading to some confusion.
Clarify that both gitgitgadget/git and git/git can be used, albeit with some differences.
---
doc:clarify which remotes can be used when contributing
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2034%2FDanieleSassoli%2Fclarify-remote-to-use-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2034/DanieleSassoli/clarify-remote-to-use-v2
Pull-Request: https://github.com/git/git/pull/2034
Range-diff vs v1:
1: 850097696a4 ! 1: b34070c03e3 doc:clarify which remotes can be used when contributing
@@ Documentation/MyFirstContribution.adoc: Now you should be able to go and check o
In order to have your code tested and formatted for review, you need to start by
-opening a Pull Request against gitgitgadget/git. Head to
-+opening a Pull Request against either gitgitgadget/git or git/git, depending
-+on which mirror you initially cloned from. Head to
- https://github.com/gitgitgadget/git and open a PR either with the "New pull
- request" button or the convenient "Compare & pull request" button that may
- appear with the name of your newly pushed branch.
-+If you're using https://github.com/git/git as your remote, you will need to
-+open the pull-request from your fork, selecting git/git as base. +-https://github.com/gitgitgadget/git and open a PR either with the "New pull
+-request" button or the convenient "Compare & pull request" button that may
+-appear with the name of your newly pushed branch.
++opening a Pull Request against either gitgitgadget/git or git/git. Head to ++https://github.com/gitgitgadget/git or https://github.com/git/git and open a PR
++either with the "New pull request" button or the convenient "Compare & pull
++request" button that may appear with the name of your newly pushed branch.
+
+The differences between using gitgitgadget/git and git/git as your base can
+be found [here](https://gitgitgadget.github.io/#should-i-use-gitgitgadget-on-gitgitgadgets-git-fork-or-on-gits-github-mirror)
Documentation/MyFirstContribution.adoc | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-)
Documentation/MyFirstContribution.adoc +7 -4
@@ -908,10 +908,13 @@ Now you should be able to go and check out your newly created branch on GitHub. === Sending a PR to GitGitGadget In order to have your code tested and formatted for review, you need to start by -opening a Pull Request against `gitgitgadget/git`. Head to -https://github.com/gitgitgadget/git and open a PR either with the "New pull -request" button or the convenient "Compare & pull request" button that may -appear with the name of your newly pushed branch. +opening a Pull Request against either `gitgitgadget/git` or `git/git`. Head to +https://github.com/gitgitgadget/git or https://github.com/git/git and open a PR +either with the "New pull request" button or the convenient "Compare & pull +request" button that may appear with the name of your newly pushed branch. + +The differences between using `gitgitgadget/git` and `git/git` as your base can +be found [here](https://gitgitgadget.github.io/#should-i-use-gitgitgadget-on-gitgitgadgets-git-fork-or-on-gits-github-mirror) Review the PR's title and description, as they're used by GitGitGadget respectively as the subject and body of the cover letter for your change. Refer
base-commit: 1fa68948c3d76328236cac73d2adf33c905bd8e3
Signature · 1 line
gitgitgadget
Quoted 73 lines · Daniele Sassoli via GitGitGadget
From: Daniele Sassoli <[email protected]>
The docs mostly point to using git/git as one's remote, however, when it comes to Sending a PR to GitGitGadget section, the reader is told to use gitgitgadget/git, with no mention of git/git, potentially leading to some confusion.
Clarify that both gitgitgadget/git and git/git can be used, albeit with some differences.
Signed-off-by Daniele Sassoli <[email protected]>---
doc:clarify which remotes can be used when contributingcc Elijah Newren [email protected]Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2034%2FDanieleSassoli%2Fclarify-remote-to-use-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2034/DanieleSassoli/clarify-remote-to-use-v2
Pull-Request: https://github.com/git/git/pull/2034Range-diff vs v1:
1:
850097696a4! 1:b34070c03e3doc:clarify which remotes can be used when contributing
@@Documentation/MyFirstContribution.adoc: Now you should be able to go and check oIn order to have your code tested and formatted for review, you need to start by
-opening a Pull Request againstgitgitgadget/git. Head to
-+opening a Pull Request against eithergitgitgadget/gitorgit/git, depending
-+on which mirror you initially cloned from. Head to
- https://github.com/gitgitgadget/git and open a PR either with the "New pull
- request" button or the convenient "Compare & pull request" button that may
- appear with the name of your newly pushed branch.
-+If you're using https://github.com/git/git as your remote, you will need to
-+open the pull-request from your fork, selectinggit/gitas base. +-https://github.com/gitgitgadget/git and open a PR either with the "New pull
+-request" button or the convenient "Compare & pull request" button that may
+-appear with the name of your newly pushed branch.
++opening a Pull Request against eithergitgitgadget/gitorgit/git. Head to ++https://github.com/gitgitgadget/git or https://github.com/git/git and open a PR
++either with the "New pull request" button or the convenient "Compare & pull
++request" button that may appear with the name of your newly pushed branch.
+
+The differences between usinggitgitgadget/gitandgit/gitas your base can
+be found [here](https://gitgitgadget.github.io/#should-i-use-gitgitgadget-on-gitgitgadgets-git-fork-or-on-gits-github-mirror)Documentation/MyFirstContribution.adoc | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-)Documentation/MyFirstContribution.adoc +7
-4@@ -908,10 +908,13 @@ Now you should be able to go and check out your newly created branch on GitHub. === Sending a PR to GitGitGadget In order to have your code tested and formatted for review, you need to start by -opening a Pull Request against `gitgitgadget/git`. Head to -https://github.com/gitgitgadget/git and open a PR either with the "New pull -request" button or the convenient "Compare & pull request" button that may -appear with the name of your newly pushed branch. +opening a Pull Request against either `gitgitgadget/git` or `git/git`. Head to +https://github.com/gitgitgadget/git or https://github.com/git/git and open a PR +either with the "New pull request" button or the convenient "Compare & pull +request" button that may appear with the name of your newly pushed branch. + +The differences between using `gitgitgadget/git` and `git/git` as your base can +be found [here](https://gitgitgadget.github.io/#should-i-use-gitgitgadget-on-gitgitgadgets-git-fork-or-on-gits-github-mirror) Review the PR's title and description, as they're used by GitGitGadget respectively as the subject and body of the cover letter for your change. Refer
Quoted 3 lines
base-commit:
1fa68948c3d76328236cac73d2adf33c905bd8e3--
gitgitgadget
This version looks good to me; thanks!
Quoted 5 lines · Elijah Newren
Quoted 3 lines · Daniele Sassoli via GitGitGadget
From: Daniele Sassoli <[email protected]>
Quoted 7 lines
Quoted 5 lines
The docs mostly point to using git/git as one's remote, however, when it comes to Sending a PR to GitGitGadget section, the reader is told to use gitgitgadget/git, with no mention of git/git, potentially leading to some confusion.
...This version looks good to me; thanks!
Thanks both. I'll queue it after reritling.
Quoted 1 line
doc: clarify which remotes can be used with GitGitGadget
The only reason why you need to even "use" remote is because you are using GGG; othrewise you would not even be using any when sending your contribution in, so "when contributing" somewhat misses the point.
Quoted 11 lines · Junio C Hamano
Quoted 9 lines · Elijah Newren
Quoted 7 lines · Daniele Sassoli via GitGitGadget
From: Daniele Sassoli <[email protected]>
The docs mostly point to using git/git as one's remote, however, when it comes to Sending a PR to GitGitGadget section, the reader is told to use gitgitgadget/git, with no mention of git/git, potentially leading to some confusion.
...
Quoted 8 lines
Quoted 1 line
This version looks good to me; thanks!
Thanks both. I'll queue it after reritling.
Quoted 1 line
doc: clarify which remotes can be used with GitGitGadget
The only reason why you need to even "use" remote is because you are using GGG; othrewise you would not even be using any when sending your contribution in, so "when contributing" somewhat misses the point.
Makes sense, thanks for your help.