shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-12-25 01:34:28 +03:00
Code
ba592dc715
systemd/docs/CODE_QUALITY.md

86 lines
4.0 KiB
Markdown
Raw Normal View History

docs: add a "front matter" snippet to our markdown pages It turns out Jekyll (the engine behind GitHub Pages) requires that pages include a "Front Matter" snippet of YAML at the top for proper rendering. Omitting it will still render the pages, but including it opens up new possibilities, such as using a {% for %} loop to generate index.md instead of requiring a separate script. I'm hoping this will also fix the issue with some of the pages (notably CODE_OF_CONDUCT.html) not being available under systemd.io Tested locally by rendering the website with Jekyll. Before this change, the *.md files were kept unchanged (so not sure how that even works?!), after this commit, proper *.html files were generated from it.
2019-01-03 01:16:34 +03:00
---
title: Code Quality Tools
docs: place all our markdown docs in rough categories
2019-12-11 12:49:28 +03:00
category: Contributing
docs: make it pretty Add custom Jekyll theme, logo, webfont and .gitignore FIXME: the markdown files have some H1 headers which need to be replaced with H2
2019-12-11 19:01:46 +03:00
layout: default
docs: add spdx tags to all .md files I have no idea if this is going to cause rendering problems, and it is fairly hard to check. So let's just merge this, and if it github markdown processor doesn't like it, revert.
2021-09-14 17:05:21 +03:00
SPDX-License-Identifier: LGPL-2.1-or-later
docs: add a "front matter" snippet to our markdown pages It turns out Jekyll (the engine behind GitHub Pages) requires that pages include a "Front Matter" snippet of YAML at the top for proper rendering. Omitting it will still render the pages, but including it opens up new possibilities, such as using a {% for %} loop to generate index.md instead of requiring a separate script. I'm hoping this will also fix the issue with some of the pages (notably CODE_OF_CONDUCT.html) not being available under systemd.io Tested locally by rendering the website with Jekyll. Before this change, the *.md files were kept unchanged (so not sure how that even works?!), after this commit, proper *.html files were generated from it.
2019-01-03 01:16:34 +03:00
---
doc: add a list of code quality tools we have set up Also, as a reminder all of these exist to myself.
2018-06-07 16:07:23 +03:00
# Code Quality Tools
The systemd project has a number of code quality tools set up in the source
tree and on the github infrastructure. Here's an incomprehensive list of the
available functionality:
tree-wide: suggest meson command lines instead of ninja ones This only changes documentation. In various places we call "ninja" directly. I figured it would be safer to leave those in place for now, given the meson replacement commands lines appears to be supported in newer meson versions only.
2020-12-11 13:33:39 +03:00
1. Use `meson test -C build` to run the unit tests. Some tests are skipped if
doc: add a list of code quality tools we have set up Also, as a reminder all of these exist to myself.
2018-06-07 16:07:23 +03:00
no privileges are available, hence consider also running them with `sudo
tree-wide: suggest meson command lines instead of ninja ones This only changes documentation. In various places we call "ninja" directly. I figured it would be safer to leave those in place for now, given the meson replacement commands lines appears to be supported in newer meson versions only.
2020-12-11 13:33:39 +03:00
meson test -C build`. A couple of unit tests are considered "unsafe" (as
they change system state); to run those too, build with `meson setup
doc: add a list of code quality tools we have set up Also, as a reminder all of these exist to myself.
2018-06-07 16:07:23 +03:00
-Dtests=unsafe`. Finally, some unit tests are considered to be very slow,
tree-wide: suggest meson command lines instead of ninja ones This only changes documentation. In various places we call "ninja" directly. I figured it would be safer to leave those in place for now, given the meson replacement commands lines appears to be supported in newer meson versions only.
2020-12-11 13:33:39 +03:00
build them too with `meson setup -Dslow-tests=true`. (Note that there are a
couple of manual tests in addition to these unit tests.) (Also note: you can
change these flags for an already set up build tree, too, with "meson
configure -C build -D…".)
doc: add a list of code quality tools we have set up Also, as a reminder all of these exist to myself.
2018-06-07 16:07:23 +03:00
2. Use `./test/run-integration-tests.sh` to run the full integration test
suite. This will build OS images with a number of integration tests and run
docs: fix formatting a bit
2023-01-15 11:00:00 +03:00
them using `systemd-nspawn` and `qemu`. Requires root.
doc: add a list of code quality tools we have set up Also, as a reminder all of these exist to myself.
2018-06-07 16:07:23 +03:00
3. Use `./coccinelle/run-coccinelle.sh` to run all
[Coccinelle](http://coccinelle.lip6.fr/) semantic patch scripts we ship. The
output will show false positives, hence take it with a pinch of salt.
4. Use `./tools/find-double-newline.sh recdiff` to find double newlines. Use
`./tools/find-double-newline.sh recpatch` to fix them. Take this with a grain
of salt, in particular as we generally leave foreign header files we include in
our tree unmodified, if possible.
5. Similar use `./tools/find-tabs.sh recdiff` to find TABs, and
`./tools/find-tabs.sh recpatch` to fix them. (Again, grain of salt, foreign
headers should usually be left unmodified.)
docs: stop recommending meson compile With meson-0.60, meson compile stopped working with some targets: $ meson compile -C build update-man-rules ERROR: Can't invoke target `update-man-rules`: ambiguous name. Add target type and/or path: `PATH/NAME:TYPE` This is obviously a regression in meson, but based on a chat with the maintainers, it seems that there's some disagreement as to whether 'meson compile' is useful and how exactly it should work. Since we're already at meson 0.60.3 and this hasn't been fixed, and people generally don't seem to consider this an issue, let's return to documenting the usual practice of 'ninja -C build' that just works everywhere. (Since nobody has raised any fuss in systemd, it means that people are generally using the shorter form during development too. I only noticed because I pasted a command from the release docs when preparing -rc1.)
2022-04-12 13:05:53 +03:00
6. Use `ninja -C build check-api-docs` to compare the list of exported symbols
of `libsystemd.so` and `libudev.so` with the list of man pages. Symbols
doc: add a list of code quality tools we have set up Also, as a reminder all of these exist to myself.
2018-06-07 16:07:23 +03:00
lacking documentation are highlighted.
docs: stop recommending meson compile With meson-0.60, meson compile stopped working with some targets: $ meson compile -C build update-man-rules ERROR: Can't invoke target `update-man-rules`: ambiguous name. Add target type and/or path: `PATH/NAME:TYPE` This is obviously a regression in meson, but based on a chat with the maintainers, it seems that there's some disagreement as to whether 'meson compile' is useful and how exactly it should work. Since we're already at meson 0.60.3 and this hasn't been fixed, and people generally don't seem to consider this an issue, let's return to documenting the usual practice of 'ninja -C build' that just works everywhere. (Since nobody has raised any fuss in systemd, it means that people are generally using the shorter form during development too. I only noticed because I pasted a command from the release docs when preparing -rc1.)
2022-04-12 13:05:53 +03:00
7. Use `ninja -C build update-hwdb` and `ninja -C build update-hwdb-autosuspend`
to automatically download and import the PCI, USB, and OUI databases and the
autosuspend quirks into the hwdb.
doc: add a list of code quality tools we have set up Also, as a reminder all of these exist to myself.
2018-06-07 16:07:23 +03:00
docs: stop recommending meson compile With meson-0.60, meson compile stopped working with some targets: $ meson compile -C build update-man-rules ERROR: Can't invoke target `update-man-rules`: ambiguous name. Add target type and/or path: `PATH/NAME:TYPE` This is obviously a regression in meson, but based on a chat with the maintainers, it seems that there's some disagreement as to whether 'meson compile' is useful and how exactly it should work. Since we're already at meson 0.60.3 and this hasn't been fixed, and people generally don't seem to consider this an issue, let's return to documenting the usual practice of 'ninja -C build' that just works everywhere. (Since nobody has raised any fuss in systemd, it means that people are generally using the shorter form during development too. I only noticed because I pasted a command from the release docs when preparing -rc1.)
2022-04-12 13:05:53 +03:00
8. Use `ninja -C build update-man-rules` to update the meson rules for building
man pages automatically from the docbook XML files included in `man/`.
doc: add a list of code quality tools we have set up Also, as a reminder all of these exist to myself.
2018-06-07 16:07:23 +03:00
docs: stop recommending meson compile With meson-0.60, meson compile stopped working with some targets: $ meson compile -C build update-man-rules ERROR: Can't invoke target `update-man-rules`: ambiguous name. Add target type and/or path: `PATH/NAME:TYPE` This is obviously a regression in meson, but based on a chat with the maintainers, it seems that there's some disagreement as to whether 'meson compile' is useful and how exactly it should work. Since we're already at meson 0.60.3 and this hasn't been fixed, and people generally don't seem to consider this an issue, let's return to documenting the usual practice of 'ninja -C build' that just works everywhere. (Since nobody has raised any fuss in systemd, it means that people are generally using the shorter form during development too. I only noticed because I pasted a command from the release docs when preparing -rc1.)
2022-04-12 13:05:53 +03:00
9. There are multiple CI systems in use that run on every github pull request
submission or update.
doc: add a list of code quality tools we have set up Also, as a reminder all of these exist to myself.
2018-06-07 16:07:23 +03:00
docs: update branch names Also use --atomic when pushing multiple items with git; adjust some external URLs.
2021-12-23 23:25:31 +03:00
10. [Coverity](https://scan.coverity.com/) is analyzing systemd `main` branch
in regular intervals. The reports are available
doc: add a list of code quality tools we have set up Also, as a reminder all of these exist to myself.
2018-06-07 16:07:23 +03:00
[online](https://scan.coverity.com/projects/systemd).
docs: update OSS-Fuzz links
2022-05-26 17:07:32 +03:00
11. [OSS-Fuzz](https://github.com/google/oss-fuzz) is continuously fuzzing the
doc: add a list of code quality tools we have set up Also, as a reminder all of these exist to myself.
2018-06-07 16:07:23 +03:00
codebase. Reports are available
docs: update OSS-Fuzz links
2022-05-26 17:07:32 +03:00
[online](https://oss-fuzz.com/testcases?project=systemd&open=yes).
It also builds
[coverage reports](https://oss-fuzz.com/coverage-report/job/libfuzzer_asan_systemd/latest)
daily.
doc: add a list of code quality tools we have set up Also, as a reminder all of these exist to myself.
2018-06-07 16:07:23 +03:00
doc: extend CODE_QUALITY.md with two more items
2018-06-12 13:03:13 +03:00
12. Our tree includes `.editorconfig`, `.dir-locals.el` and `.vimrc` files, to
NEWS, CODE_QUALITY: wording fixes No additions, just moving stuff around and wording cleanups.
2018-06-12 15:06:13 +03:00
ensure that editors follow the right indentiation styles automatically.
doc: extend CODE_QUALITY.md with two more items
2018-06-12 13:03:13 +03:00
13. When building systemd from a git checkout the build scripts will
NEWS, CODE_QUALITY: wording fixes No additions, just moving stuff around and wording cleanups.
2018-06-12 15:06:13 +03:00
automatically enable a git commit hook that ensures whitespace cleanliness.
doc: extend CODE_QUALITY.md with two more items
2018-06-12 13:03:13 +03:00
doc: drop remaining references to LGTM.com
2022-09-23 01:54:12 +03:00
14. [CodeQL](https://codeql.github.com/) analyzes each PR and every commit
pushed to `main`. The list of active alerts can be found
[here](https://github.com/systemd/systemd/security/code-scanning).
docs: put LGTM on the list of QA tools and fix a couple typos
2018-06-23 19:53:04 +03:00
docs: add documentation for sanitizers
2019-05-27 15:14:26 +03:00
15. Each PR is automatically tested with [Address Sanitizer](https://clang.llvm.org/docs/AddressSanitizer.html)
and [Undefined Behavior Sanitizer](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html).
docs: use absolute links for our pages Since 56b2970 has proven to be a no-go for us, as it breaks existing links, let's embrace the trailing slash and use absolute links everywhere for our pages. This way we'll get around browser cleverly appending the relative link to the current location (since it ends with a slash), and given our docs/ layout is flat it's not much of a hassle either. Converted using this beauty: $ sed -ri 's/(\[.+\]\()([A-Z_]+\))/\1\/\2/g' *.md Resolves: #32088 (again) and #32310
2024-04-17 21:54:45 +03:00
See [Testing systemd using sanitizers](/TESTING_WITH_SANITIZERS)
docs: add documentation for sanitizers
2019-05-27 15:14:26 +03:00
for more information.
docs: add a link to the Fossies codespell report
2020-05-21 10:00:53 +03:00
16. Fossies provides [source code misspelling reports](https://fossies.org/features.html#codespell).
docs: update branch names Also use --atomic when pushing multiple items with git; adjust some external URLs.
2021-12-23 23:25:31 +03:00
The systemd report can be found [here](https://fossies.org/linux/misc/systemd/codespell.html).
docs: add a link to the Fossies codespell report
2020-05-21 10:00:53 +03:00
docs: put LGTM on the list of QA tools and fix a couple typos
2018-06-23 19:53:04 +03:00
Access to Coverity and oss-fuzz reports is limited. Please reach out to the
maintainers if you need access.
Copy Permalink