* contributing.mdwn: link to the developer-workflows page. * contributing/developer-workflows.mdwn: new file. * hurd/building.mdwn: tweaked some commands. --- contributing.mdwn | 6 ++ contributing/developer-workflows.mdwn | 110 ++++++++++++++++++++++++++ hurd/building.mdwn | 10 ++- 3 files changed, 123 insertions(+), 3 deletions(-) create mode 100644 contributing/developer-workflows.mdwn
diff --git a/contributing.mdwn b/contributing.mdwn index 6666e242..ed39344b 100644 --- a/contributing.mdwn +++ b/contributing.mdwn @@ -242,6 +242,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..6e94661a --- /dev/null +++ b/contributing/developer-workflows.mdwn @@ -0,0 +1,110 @@ +[[!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. + + $ git format-patch -4 --to-bug-h...@gnu.org \ + --cover-letter --cc=hurdexp...@gnu.org + $ 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. + +# Develop the Debian way + +You can develop the GNU/Hurd via Debian GNU/Hurd. This [Hurd wiki +page](https://www.debian.org/ports/hurd/hurd-devel-debian) has more +information. + +This page describes how to [[build|hurd/building]] the hurd. diff --git a/hurd/building.mdwn b/hurd/building.mdwn index ea3213e5..0e25cf53 100644 --- a/hurd/building.mdwn +++ b/hurd/building.mdwn @@ -25,7 +25,7 @@ dependencies and additional packages that are specified by the source hurd package: # apt install build-essential fakeroot - # apt build-dep hurd + # apt build-dep -y hurd gnumach ## ... on non-Debian systems @@ -41,7 +41,11 @@ git](http://savannah.gnu.org/git/?group=hurd): ... or (if you are working on a Debian system) the ones that are used for the [current Debian hurd package](http://packages.debian.net/source/unstable/hurd): - $ apt source hurd + $ git clone https://salsa.debian.org/hurd-team/hurd.git + +Or you could use apt source + + $ apt source hurd Please see the Debian [[FAQ]] before using `apt source`. @@ -60,7 +64,7 @@ If you want to work on the sources before building them, it's advisable to first make sure that patches that the Debian hurd package additionally contains are applied: - $ dh_quilt_patch + $ dh_quilt_patch Then edit and change whatever files you want and finally start the build process with -- 2.50.1
