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).

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 ,