On Tue, Jul 19, 2022 at 07:52:33PM +0200, Stefan Sperling wrote:
> The question "can Got do pull requests" has come up from time
> to time in conversations I have had with various people.
> Such questions usually pertain to work people do outside of
> OpenBSD, or when ports developers submit patches upstream.
> 
> Would it be useful to document how to work with pull requests?
> Or should we assume people are clever enough to put the necessary
> bits and piece together by reading the existing documentation?
> 
> An experienced user will find the example I am adding fairly trivial,
> but this isn't aimed at them. And many people will be patient enough
> to figure things out on their own. But I would assume we will have
> some readers who will give up quickly unless they find an obvious
> solution by searching the man page for terms like "pull", "github",
> "squash", and such. This is who I am aiming at with the example below.
> 
> I am using a real-life example because this is fresh on my mind as I
> went through this today, and because trying to make up fictional account
> names for large websites like github.com has potential for clashing with
> real accounts (github.com/alice and github.com/bob do already exist).

I like the addition of multiple examples. ok by me.

> 
> diff 314c3f148b7679296136b460ea9a8f0d4c74d437 fd53638cb69ba944791ba9f9f2a3aca286f1acc4
> commit - 314c3f148b7679296136b460ea9a8f0d4c74d437
> commit + fd53638cb69ba944791ba9f9f2a3aca286f1acc4
> blob - e40b2fea7364f818d1cc038e58b39c5e8b17968b
> blob + 3d8de774891ad511d038cafc4c9304dbe4c6ebb1
> --- got/got.1
> +++ got/got.1
> @@ -3104,6 +3104,95 @@ command must be used instead:
>  .Pp
>  .Dl $ cd /var/git/src.git
>  .Dl $ git push origin master
> +.Pp
> +When making contributions to projects which use the
> +.Dq pull request
> +workflow, SSH protocol repository access needs to be set up first.
> +Once an account has been created on a Git hosting site it should
> +be possible to upload a public SSH key for repository access
> +authentication.
> +.Pp
> +The
> +.Dq pull request
> +workflow will usually involve two remote repositories.
> +In the real-life example below, the
> +.Dq origin
> +repository was forked from the
> +.Dq upstream
> +repository by using the Git hosting site's web interface:
> +.Bd -literal -offset indent
> +# Jelmers's repository, which accepts pull requests
> +remote "upstream" {
> +	server git@github.com
> +	protocol ssh
> +	repository "/jelmer/dulwich"
> +	branch { "master" }
> +}
> +
> +# Stefan's fork, used as the default remote repository
> +remote "origin" {
> +	server git@github.com
> +	protocol ssh
> +	repository "/stspdotname/dulwich"
> +	branch { "master" }
> +}
> +.Ed
> +.Pp
> +With this configuration, Stefan can create commits on
> +.Dq refs/heads/master
> +and send them to the
> +.Dq origin
> +repository by running:
> +.Pp
> +.Dl $ got send -b master origin
> +.Pp
> +The changes can now be proposed to Jelmer by opening a pull request
> +via the Git hosting site's web interface.
> +If Jelmer requests further changes to be made, additional commits
> +can be created on the
> +.Dq master
> +branch and be added to the pull request by running
> +.Cd got send
> +again.
> +.Pp
> +If Jelmer prefers additional commits to be
> +.Dq squashed
> +then the following commands can be used to achieve this:
> +.Pp
> +.Dl $ got update -b master
> +.Dl $ got update -c origin/master
> +.Dl $ got histedit -f
> +.Dl $ got send -f -b master origin
> +.Pp
> +Once Jelmer has accepted the pull request, Stefan can fetch the
> +merged changes, and possibly several other new changes, by running:
> +.Pp
> +.Dl $ got fetch upstream
> +.Pp
> +The merged changes will now be visible under the reference
> +.Dq refs/remotes/upstream/master .
> +The local
> +.Dq master
> +branch can now be rebased on top of the latest changes
> +from upstream:
> +.Pp
> +.Dl $ got update -b upstream/master
> +.Dl $ got rebase master
> +.Pp
> +As a final step, the forked repository's copy of the master branch needs
> +to be kept in sync by sending the new changes there:
> +.Pp
> +.Dl $ got send -f -b master origin
> +.Pp
> +If multiple pull requests need to be managed in parallel, a separate branch
> +must be created for each pull request with
> +.Cm got branch .
> +Each such branch can then be used as above, in place of
> +.Dq refs/heads/master .
> +Changes for any accepted pull requests will still appear under
> +.Dq refs/remotes/upstream/master,
> +regardless of which branch was used in the forked repository to
> +create a pull request.
>  .Sh SEE ALSO
>  .Xr gotadmin 1 ,
>  .Xr tog 1 ,
> 

-- 

Tracey Emery