doc:clarify which remotes can be used when contributing #2034
+7
−4
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
There are issues in commit b45c1af: |
29e7530 to
8500976
Compare
|
/submit |
|
Submitted as pull.2034.git.git.1755630882418.gitgitgadget@gmail.com To fetch this version into To fetch this version to local tag |
|
On the Git mailing list, Junio C Hamano wrote (reply to this): "Daniele Sassoli via GitGitGadget" <gitgitgadget@gmail.com> writes:
> 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)
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. |
|
On the Git mailing list, Daniele Sassoli wrote (reply to this): On 19/08/2025 22:19, Junio C Hamano wrote:
> "Daniele Sassoli via GitGitGadget" <gitgitgadget@gmail.com> writes:
>> 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)
> 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
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.
> 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. |
|
On the Git mailing list, Junio C Hamano wrote (reply to this): Daniele Sassoli <danielesassoli@gmail.com> writes:
> On 19/08/2025 22:19, Junio C Hamano wrote:
>> "Daniele Sassoli via GitGitGadget" <gitgitgadget@gmail.com> writes:
>>> 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)
>> Looking at the table, there is no advantage to use git/git at all.
>
> 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.
|
|
On the Git mailing list, Daniele Sassoli wrote (reply to this): On 20/08/2025 22:16, Junio C Hamano wrote:
> Daniele Sassoli <danielesassoli@gmail.com> writes:
>
>> On 19/08/2025 22:19, Junio C Hamano wrote:
>>> "Daniele Sassoli via GitGitGadget" <gitgitgadget@gmail.com> writes:
>>>> 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)
>>> Looking at the table, there is no advantage to use git/git at all.
>> 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.
> 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.
>
> 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.
> |
|
On the Git mailing list, Junio C Hamano wrote (reply to this): Daniele Sassoli <danielesassoli@gmail.com> writes:
> Subject: Re: [PATCH] doc:clarify which remotes can be used when contributing
A space is missing before "clarify".
>> 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.
> ...
> 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. |
|
On the Git mailing list, Elijah Newren wrote (reply to this): On Tue, Aug 19, 2025 at 12:14 PM Daniele Sassoli via GitGitGadget
<gitgitgadget@gmail.com> wrote:
>
> From: Daniele Sassoli <danielesassoli@gmail.com>
>
> 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 <danielesassoli@gmail.com>
> ---
> 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(-)
>
> diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc
> index aca7212cfe2..d014c5c36e1 100644
> --- a/Documentation/MyFirstContribution.adoc
> +++ b/Documentation/MyFirstContribution.adoc
> @@ -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.
> 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.
...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.)
> +
> +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.
> 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
> --
> gitgitgadget
Thanks for sending the patch in. |
|
User |
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 <danielesassoli@gmail.com>
8500976 to
b34070c
Compare
|
/submit |
|
Submitted as pull.2034.v2.git.git.1755940331248.gitgitgadget@gmail.com To fetch this version into To fetch this version to local tag |
|
On the Git mailing list, Elijah Newren wrote (reply to this): On Sat, Aug 23, 2025 at 2:12 AM Daniele Sassoli via GitGitGadget
<gitgitgadget@gmail.com> wrote:
>
> From: Daniele Sassoli <danielesassoli@gmail.com>
>
> 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 <danielesassoli@gmail.com>
> ---
> doc:clarify which remotes can be used when contributing
>
> cc: Elijah Newren newren@gmail.com
>
> 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(-)
>
> diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc
> index aca7212cfe2..bbb7b45bd4a 100644
> --- a/Documentation/MyFirstContribution.adoc
> +++ b/Documentation/MyFirstContribution.adoc
> @@ -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
> --
> gitgitgadget
This version looks good to me; thanks! |
|
On the Git mailing list, Junio C Hamano wrote (reply to this): Elijah Newren <newren@gmail.com> writes:
> On Sat, Aug 23, 2025 at 2:12 AM Daniele Sassoli via GitGitGadget
> <gitgitgadget@gmail.com> wrote:
>>
>> From: Daniele Sassoli <danielesassoli@gmail.com>
>>
>> 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.
> 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.
|
|
This patch series was integrated into seen via cf59e6a. |
|
This patch series was integrated into next via 71aea64. |
|
On the Git mailing list, Daniele Sassoli wrote (reply to this): On 25/08/2025 17:21, Junio C Hamano wrote:
> Elijah Newren <newren@gmail.com> writes:
>
>> On Sat, Aug 23, 2025 at 2:12 AM Daniele Sassoli via GitGitGadget
>> <gitgitgadget@gmail.com> wrote:
>>> From: Daniele Sassoli <danielesassoli@gmail.com>
>>>
>>> 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.
>
>> 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.
>
> |
|
This branch is now known as |
|
This patch series was integrated into seen via a3ad697. |
|
This patch series was integrated into seen via 30159e4. |
|
This patch series was integrated into seen via ddebaea. |
|
There was a status update in the "Cooking" section about the branch Update the instruction to use of GGG in the MyFirstContribution document to say that a GitHub PR could be made against `git/git` instead of `gitgitgadget/git`. Will merge to 'master'. cf. <xmqqtt1vs77x.fsf@gitster.g> source: <pull.2034.v2.git.git.1755940331248.gitgitgadget@gmail.com> |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
cc: Elijah Newren newren@gmail.com