Download raw body.
document pull request workflow
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
document pull request workflow