doc: Document “standard” pull requests and AGit.

* doc/contributing.texi (Submitting Patches): Document “standard” pull
requests and AGit.

Merges guix/guix!5840

Change-Id: I8fe93e4dde0b9543f3bd99c66cf1fdb6ba69c449
Signed-off-by: Cayetano Santos <csantosb@inventati.org>

1 files changed, 41 insertions, 0 deletions

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 1f23f92b844..eb5e7f760a1 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -1960,6 +1960,47 @@ contributions as @dfn{pull requests} (PR) at
 @uref{https://codeberg.org/guix/guix-consensus-documents/src/branch/main/002-codeberg.md,
 Guix Consensus Document 002}, this method is no longer supported.}.
 
+There are two ways to create a pull request:
+
+@itemize
+@item
+By creating a personal ``fork'' of @uref{https://codeberg.org/guix/guix,
+the repository}, creating a branch with your changes, and
+@uref{https://docs.codeberg.org/collaborating/pull-requests-and-git-flow/,
+submitting a pull request for that branch}.
+
+@item
+@cindex AGit workflow, for pull requests
+By following the @uref{https://forgejo.org/docs/next/user/agit-support/,
+@dfn{AGit workflow}}, which is somewhat more convenient and consumes
+less disk space at Codeberg since it removes the need to create a
+``fork''.
+
+Assuming your local checkout is on the branch containing the changes you
+would like to submit for inclusion in the @code{master} branch, run:
+
+@example
+git push origin HEAD:refs/for/master \
+  -o topic=@var{topic} \
+  -o title=@var{title} -o description=@var{description}
+@end example
+
+@var{topic} must be an identifier without whitespace, similar to a
+branch name; @var{title} and @var{description} are arbitrary text that
+can be omitted, in which case the message of the last commit on the
+branch fills that role.
+
+To send an update to an AGit pull request of yours, run:
+
+@example
+git push origin HEAD:refs/for/master \
+  -o topic=@var{topic} -o force-push=yes
+@end example
+
+Codeberg automatically figures out which pull request @var{topic}
+corresponds to and updates the associated branch.
+@end itemize
+
 Contributors are encouraged to take a moment to set some Git
 repository options (@pxref{Configuring Git}) first, which can improve
 the readability of patches.  Seasoned Guix developers may also want to