docs: Convert HACKING to Markdown

Also fix minor grammatical errors

diff --git a/docs/HACKING b/docs/HACKING
deleted file mode 100644 (file)
index c975ca1..0000000
--- a/docs/HACKING
+++ /dev/null
@@ -1,122 +0,0 @@
-HACKING ON SYSTEMD
-
-We welcome all contributions to systemd. If you notice a bug or a missing
-feature, please feel invited to fix it, and submit your work as a github Pull
-Request (PR):
-
-        https://github.com/systemd/systemd/pull/new
-
-Please make sure to follow our Coding Style when submitting patches. See
-docs/CODING_STYLE for details. Also have a look at our Contribution Guidelines:
-
-        https://github.com/systemd/systemd/blob/master/docs/CONTRIBUTING.md
-
-When adding new functionality, tests should be added. For shared functionality
-(in src/basic and src/shared) unit tests should be sufficient. The general
-policy is to keep tests in matching files underneath src/test,
-e.g. src/test/test-path-util.c contains tests for any functions in
-src/basic/path-util.c. If adding a new source file, consider adding a matching
-test executable. For features at a higher level, tests in src/test/ are very
-strongly recommended. If that is no possible, integration tests in test/ are
-encouraged.
-
-Please also have a look at our list of code quality tools we have setup for systemd,
-to ensure our codebase stays in good shape:
-
-        https://github.com/systemd/systemd/blob/master/docs/CODE_QUALITY.md
-
-Please always test your work before submitting a PR. For many of the components
-of systemd testing is straight-forward as you can simply compile systemd and
-run the relevant tool from the build directory.
-
-For some components (most importantly, systemd/PID1 itself) this is not
-possible, however. In order to simplify testing for cases like this we provide
-a set of "mkosi" build files directly in the source tree. "mkosi" is a tool for
-building clean OS images from an upstream distribution in combination with a
-fresh build of the project in the local working directory. To make use of this,
-please acquire "mkosi" from https://github.com/systemd/mkosi first, unless your
-distribution has packaged it already and you can get it from there. After the
-tool is installed it is sufficient to type "mkosi" in the systemd project
-directory to generate a disk image "image.raw" you can boot either in
-systemd-nspawn or in an UEFI-capable VM:
-
-        # systemd-nspawn -bi image.raw
-
-or:
-
-        # qemu-system-x86_64 -enable-kvm -m 512 -smp 2 -bios /usr/share/edk2/ovmf/OVMF_CODE.fd -hda image.raw
-
-Every time you rerun the "mkosi" command a fresh image is built, incorporating
-all current changes you made to the project tree.
-
-Alternatively, you may install the systemd version from your git check-out
-directly on top of your host system's directory tree. This mostly works fine,
-but of course you should know what you are doing as you might make your system
-unbootable in case of a bug in your changes. Also, you might step into your
-package manager's territory with this. Be careful!
-
-And never forget: most distributions provide very simple and convenient ways to
-install all development packages necessary to build systemd. For example, on
-Fedora the following command line should be sufficient to install all of
-systemd's build dependencies:
-
-        # dnf builddep systemd
-
-Putting this all together, here's a series of commands for preparing a patch
-for systemd (this example is for Fedora):
-
-        $ sudo dnf builddep systemd            # install build dependencies
-        $ sudo dnf install mkosi               # install tool to quickly build images
-        $ git clone https://github.com/systemd/systemd.git
-        $ cd systemd
-        $ vim src/core/main.c                  # or wherever you'd like to make your changes
-        $ meson build                          # configure the build
-        $ ninja -C build                       # build it locally, see if everything compiles fine
-        $ ninja -C build test                  # run some simple regression tests
-        $ (umask 077; echo 123 > mkosi.rootpw) # set root password used by mkosi
-        $ sudo mkosi                           # build a test image
-        $ sudo systemd-nspawn -bi image.raw    # boot up the test image
-        $ git add -p                           # interactively put together your patch
-        $ git commit                           # commit it
-        $ git push REMOTE HEAD:refs/heads/BRANCH
-                                               # where REMOTE is your "fork" on github
-                                               # and BRANCH is a branch name.
-
-And after that, head over to your repo on github and click "Compare & pull request"
-
-Happy hacking!
-
-
-FUZZERS
-
-systemd includes fuzzers in src/fuzz that use libFuzzer and are automatically
-run by OSS-Fuzz (https://github.com/google/oss-fuzz) with sanitizers. To add a
-fuzz target, create a new src/fuzz/fuzz-foo.c file with a LLVMFuzzerTestOneInput
-function and add it to the list in src/fuzz/meson.build.
-
-Whenever possible, a seed corpus and a dictionary should also be added with new
-fuzz targets. The dictionary should be named src/fuzz/fuzz-foo.dict and the seed
-corpus should be built and exported as $OUT/fuzz-foo_seed_corpus.zip in
-tools/oss-fuzz.sh.
-
-The fuzzers can be built locally if you have libFuzzer installed by running
-tools/oss-fuzz.sh. You should also confirm that the fuzzer runs in the
-OSS-Fuzz environment by checking out the OSS-Fuzz repo, and then running
-commands like this:
-
-        python infra/helper.py build_image systemd
-        python infra/helper.py build_fuzzers --sanitizer memory systemd ../systemd
-        python infra/helper.py run_fuzzer systemd fuzz-foo
-
-If you find a bug that impacts the security of systemd, please follow the
-guidance in CONTRIBUTING.md on how to report a security vulnerability.
-
-For more details on building fuzzers and integrating with OSS-Fuzz, visit:
-
-        https://github.com/google/oss-fuzz/blob/master/docs/new_project_guide.md
-
-        https://llvm.org/docs/LibFuzzer.html
-
-        https://github.com/google/fuzzer-test-suite/blob/master/tutorial/libFuzzerTutorial.md
-
-        https://chromium.googlesource.com/chromium/src/testing/libfuzzer/+/HEAD/efficient_fuzzer.md

diff --git a/docs/HACKING.md b/docs/HACKING.md
new file mode 100644 (file)
index 0000000..4a7d568
--- /dev/null
+++ b/docs/HACKING.md
@@ -0,0 +1,123 @@
+# Hacking on systemd
+
+We welcome all contributions to systemd. If you notice a bug or a missing
+feature, please feel invited to fix it, and submit your work as a GitHub Pull
+Request (PR) at https://github.com/systemd/systemd/pull/new.
+
+Please make sure to follow our [Coding Style](CODING_STYLE.md) when submitting patches.
+Also have a look at our [Contribution Guidelines](CONTRIBUTING.md).
+
+When adding new functionality, tests should be added. For shared functionality
+(in `src/basic/` and `src/shared/`) unit tests should be sufficient. The general
+policy is to keep tests in matching files underneath `src/test/`,
+e.g. `src/test/test-path-util.c` contains tests for any functions in
+`src/basic/path-util.c`. If adding a new source file, consider adding a matching
+test executable. For features at a higher level, tests in `src/test/` are very
+strongly recommended. If that is no possible, integration tests in `test/` are
+encouraged.
+
+Please also have a look at our list of [code quality tools](CODE_QUALITY.md) we have setup for systemd,
+to ensure our codebase stays in good shape.
+
+Please always test your work before submitting a PR. For many of the components
+of systemd testing is straight-forward as you can simply compile systemd and
+run the relevant tool from the build directory.
+
+For some components (most importantly, systemd/PID1 itself) this is not
+possible, however. In order to simplify testing for cases like this we provide
+a set of `mkosi` build files directly in the source tree. `mkosi` is a tool for
+building clean OS images from an upstream distribution in combination with a
+fresh build of the project in the local working directory. To make use of this,
+please acquire `mkosi` from https://github.com/systemd/mkosi first, unless your
+distribution has packaged it already and you can get it from there. After the
+tool is installed it is sufficient to type `mkosi` in the systemd project
+directory to generate a disk image `image.raw` you can boot either in
+`systemd-nspawn` or in an UEFI-capable VM:
+
+```
+# systemd-nspawn -bi image.raw
+```
+
+or:
+
+```
+# qemu-system-x86_64 -enable-kvm -m 512 -smp 2 -bios /usr/share/edk2/ovmf/OVMF_CODE.fd -hda image.raw
+```
+
+Every time you rerun the `mkosi` command a fresh image is built, incorporating
+all current changes you made to the project tree.
+
+Alternatively, you may install the systemd version from your git check-out
+directly on top of your host system's directory tree. This mostly works fine,
+but of course you should know what you are doing as you might make your system
+unbootable in case of a bug in your changes. Also, you might step into your
+package manager's territory with this. Be careful!
+
+And never forget: most distributions provide very simple and convenient ways to
+install all development packages necessary to build systemd. For example, on
+Fedora the following command line should be sufficient to install all of
+systemd's build dependencies:
+
+```
+# dnf builddep systemd
+```
+
+Putting this all together, here's a series of commands for preparing a patch
+for systemd (this example is for Fedora):
+
+```sh
+$ sudo dnf builddep systemd            # install build dependencies
+$ sudo dnf install mkosi               # install tool to quickly build images
+$ git clone https://github.com/systemd/systemd.git
+$ cd systemd
+$ vim src/core/main.c                  # or wherever you'd like to make your changes
+$ meson build                          # configure the build
+$ ninja -C build                       # build it locally, see if everything compiles fine
+$ ninja -C build test                  # run some simple regression tests
+$ (umask 077; echo 123 > mkosi.rootpw) # set root password used by mkosi
+$ sudo mkosi                           # build a test image
+$ sudo systemd-nspawn -bi image.raw    # boot up the test image
+$ git add -p                           # interactively put together your patch
+$ git commit                           # commit it
+$ git push REMOTE HEAD:refs/heads/BRANCH
+                                       # where REMOTE is your "fork" on GitHub
+                                       # and BRANCH is a branch name.
+```
+
+And after that, head over to your repo on GitHub and click "Compare & pull request"
+
+Happy hacking!
+
+
+## Fuzzers
+
+systemd includes fuzzers in `src/fuzz/` that use libFuzzer and are automatically
+run by [OSS-Fuzz](https://github.com/google/oss-fuzz) with sanitizers. To add a
+fuzz target, create a new `src/fuzz/fuzz-foo.c` file with a `LLVMFuzzerTestOneInput`
+function and add it to the list in `src/fuzz/meson.build`.
+
+Whenever possible, a seed corpus and a dictionary should also be added with new
+fuzz targets. The dictionary should be named `src/fuzz/fuzz-foo.dict` and the seed
+corpus should be built and exported as `$OUT/fuzz-foo_seed_corpus.zip` in
+`tools/oss-fuzz.sh`.
+
+The fuzzers can be built locally if you have libFuzzer installed by running
+`tools/oss-fuzz.sh`. You should also confirm that the fuzzer runs in the
+OSS-Fuzz environment by checking out the OSS-Fuzz repo, and then running
+commands like this:
+
+```
+python infra/helper.py build_image systemd
+python infra/helper.py build_fuzzers --sanitizer memory systemd ../systemd
+python infra/helper.py run_fuzzer systemd fuzz-foo
+```
+
+If you find a bug that impacts the security of systemd, please follow the
+guidance in [CONTRIBUTING.md](CONTRIBUTING.md) on how to report a security vulnerability.
+
+For more details on building fuzzers and integrating with OSS-Fuzz, visit:
+
+- https://github.com/google/oss-fuzz/blob/master/docs/new_project_guide.md
+- https://llvm.org/docs/LibFuzzer.html
+- https://github.com/google/fuzzer-test-suite/blob/master/tutorial/libFuzzerTutorial.md
+- https://chromium.googlesource.com/chromium/src/testing/libfuzzer/+/HEAD/efficient_fuzzer.md