[PATCH 2/2] add developer workflows page.

[address@hidden]

* contributiing.mdwn: link to the developer-workflows page.
* contributing/developer-workflows.mdwn: new file.
---
 contributing.mdwn                     |   6 ++
 contributing/developer-workflows.mdwn | 133 ++++++++++++++++++++++++++
 2 files changed, 139 insertions(+)
 create mode 100644 contributing/developer-workflows.mdwn

diff --git a/contributing.mdwn b/contributing.mdwn
index bb6f837b..0f01e852 100644
--- a/contributing.mdwn
+++ b/contributing.mdwn
@@ -253,6 +253,12 @@ After you have a Hurd vm set up and running:
 * Start hacking.
 * For shutting down, use `reboot`, then press `c` in grub and issue halt (to 
avoid filesystem corruption). Adding `--no-reboot` to the qemu line should 
help, too.
 
+<a id="developer-workflows" name="developer-workflows"></a>
+## Developer Workflows
+
+You might want to take a look at our [[developer workflow
+recommendations|contributing/developer-workflows]].
+
 ---
 <a name="hurd_on_modern_microkernel"></a>
 # Design / Research: GNU Hurd on a Modern Microkernel
diff --git a/contributing/developer-workflows.mdwn 
b/contributing/developer-workflows.mdwn
new file mode 100644
index 00000000..7a506b18
--- /dev/null
+++ b/contributing/developer-workflows.mdwn
@@ -0,0 +1,133 @@
+[[!meta copyright="Copyright © 2024 Free Software Foundation, Inc."]]
+
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
+id="license" text="Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no Invariant
+Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
+is included in the section entitled [[GNU Free Documentation
+License|/fdl]]."]]"""]]
+
+[[!meta title="Developer Workflows"]]
+
+[[!toc levels=2]]
+
+Contributing to a free software project for the first time, can be a
+little overwhelming.  There's lots of tools that can help you
+contribute: autotools,
+[[gdb|https://www.sourceware.org/gdb/documentation/]],
+[[git|https://git-scm.com/docs/user-manual]], handling lots of email
+from mailing lists, text editors, etc.  Don't try to immediately
+master everything!  You have time to figure it all out!  Learn a
+little bit and go from there.  To help you in that process, this is a
+quick guide to get you started contributing to the Hurd:
+
+---
+
+<a id="sending-patches" name="sending-patches"></a>
+# Sending Patches
+
+The easiest way to send patches is with `git send-email`.
+[[https://git-send-email.io/]] will get you up and running with
+sending patches really quickly!
+
+To email your most recent change, you can use `git send-email` like
+so:
+
+       $ git send-email -1 --to=bug-hurd@gnu.org
+
+Where `-1` means sending the current (latest) commit; you can do more
+than 1 of course. You can do multiple `--to`'s, if you want to send
+the patch to multiple lists (e.g. both to libc-alpha and bug-hurd, for
+glibc patches), as well as `--cc` to cc specific people. It is a good
+idea to cc the people who wrote or last changed the part of code
+you are changing.
+
+If you add `--rfc`, the generated subject line will have [RFC PATCH]
+instead of [PATCH], which is roughly analogous to WIP MRs on GitLab or
+Draft PRs on GitHub, which means that you want to gather feedback, but
+don't expect the patches to merged as-is. If you post a modified
+version (aka a re-roll) of your patch (set), add -v2 (or -v3, -v4
+etc), which will result in e.g. [PATCH v2].
+
+When posting a larger patch series, you might want to generate the
+patches and send them in two distinct steps. For this, you can use git
+format-patch (with pretty much all the same options); that will
+generate a bunch of text files in your cwd that you can edit with your
+favorite text editor; Then you can email the patches via:
+
+       $ git send-email *.patch`
+
+It's oftentimes a good idea to give an overview of a patch series; for
+this you use `--cover-letter`, which will generate a dummy patch number
+0, which you can then write your description over.
+
+<a id="using-git" name="using-git"></a>
+# Using Git
+
+Git can be a little tricky to use, if you are not used to it.
+
+       $ git clone https://salsa.debian.org/hurd-team/hurd.git
+       $ cd hurd
+       $ # make a change to file
+       $ git add FILENAME
+       $ git commit -m 'trans/hello.c: Fixed a typo in a comment.'
+
+You should probably read some of the documentation from
+[git-scm.com](https://git-scm.com/doc).  `man git` is another good
+resource.
+
+<a id="text-editors" name="text-editors"></a>
+# Using Emacs' Magit
+
+The git command line is fine enough, but Emacs' magit mode makes using
+git much easier (my opinion, obviously).  With Magit, you can
+trivially re-order commits, easily reword commit messages, commit a
+change to an old commit (that is not HEAD), commit only portions of a
+file, squash commits togethor, etc.  Magit is probably one of the
+easiest ways to work with git.  You could code with any other editor,
+but just use Emacs to handle your git workflow.
+
+With magit, it is easy to create patches via highlighting one or more
+commits, and one can then type "W" followed by "c".  I personally,
+output said patches to the $hurd-src/patches directory. Then I can
+send my patches to the mailing list via:
+
+       $ cd $hurd-src/patches
+       $ git send-email --to=bug-hurd@gnu.org .
+
+# Using vim-figitive
+vim users can use vim-fugitive, which is similiar to Magit.
+
+# Using Debian's Quilt
+
+Debian GNU/Hurd uses a number of patches that are useful, but not good
+enough to commit to source just yet.  You will probably want to apply
+these patches, especially if you are using Debian GNU/Hurd.
+
+       # apt install quilt
+
+If your `$hurd-src $ git remote -v` says,
+`https://salsa.debian.org/hurd-team/hurd.git`, then you can use quilt
+to apply all of the Debian patches with:
+
+       $ quilt push -a
+
+You can learn more about quilt via `man quilt`.
+
+# Develop the Debian way
+
+You can develop the GNU/Hurd via Debian GNU/Hurd.  The [Debian
+developer's corner](https://salsa.debian.org/hurd-team/hurd.git) has
+lots of Debian specific resources.
+
+If you are using Debian GNU/Hurd, using a `salsa.debian.org` as your
+git remote, then an easy way to get started building the Hurd is to go
+to $hurd-src and run this:
+
+       # apt build-dep -y hurd gnumach
+       $ dpkg-buildpackage -us -uc -nc -b 2> compile-errors.txt
+
+This will compile the hurd source code and save any compile
+errors. `man dpkg-buildpackage` has more information.
+
-- 
2.45.2