diff --git a/.github/ISSUE_TEMPLATE/Bug_report.md b/.github/ISSUE_TEMPLATE/Bug_report.md index cea1c655b9..6a0b5527d0 100644 --- a/.github/ISSUE_TEMPLATE/Bug_report.md +++ b/.github/ISSUE_TEMPLATE/Bug_report.md @@ -8,7 +8,7 @@ about: A report of an error in a recent systemd version > ... - + **Used distribution** > … diff --git a/doc/DISTRO_PORTING b/doc/DISTRO_PORTING deleted file mode 100644 index d1a187aa41..0000000000 --- a/doc/DISTRO_PORTING +++ /dev/null @@ -1,71 +0,0 @@ -Porting systemd To New Distributions - -HOWTO: - You need to make the follow changes to adapt systemd to your - distribution: - - 1) Find the right configure parameters for: - - -D rootprefix= - -D sysvinit-path= - -D sysvrcnd-path= - -D rc-local= - -D halt-local= - -D loadkeys-path= - -D setfont-path= - -D tty-gid= - -D ntp-servers= - -D dns-servers= - -D support-url= - - 2) Try it out. Play around (as an ordinary user) with - '/usr/lib/systemd/systemd --test --system' for a test run - of systemd without booting. This will read the unit files and - print the initial transaction it would execute during boot-up. - This will also inform you about ordering loops and suchlike. - -NTP POOL: - By default, systemd-timesyncd uses the Google Public NTP servers - time[1-4].google.com, if no other NTP configuration is available. They - serve time that uses a leap second smear, and can be up to .5s off from - servers that use stepped leap seconds. - - https://developers.google.com/time/smear - - If you prefer to use leap second steps, please register your own - vendor pool at ntp.org and make it the built-in default by - passing --with-ntp-servers= to configure. Registering vendor - pools is free: - - http://www.pool.ntp.org/en/vendors.html - - Use -D ntp-servers= to direct systemd-timesyncd to different fallback - NTP servers. - -DNS SERVERS: - By default, systemd-resolved uses the Google Public DNS servers - 8.8.8.8, 8.8.4.4, 2001:4860:4860::8888, 2001:4860:4860::8844 as - fallback, if no other DNS configuration is available. - - Use -D dns-servers= to direct systemd-resolved to different fallback - DNS servers. - -PAM: - The default PAM config shipped by systemd is really bare bones. - It does not include many modules your distro might want to enable - to provide a more seamless experience. For example, limits set in - /etc/security/limits.conf will not be read unless you load pam_limits. - Make sure you add modules your distro expects from user services. - - Pass -D pamconfdir=no to meson to avoid installing this file and - instead install your own. - -CONTRIBUTING UPSTREAM: - We generally do no longer accept distribution-specific patches to - systemd upstream. If you have to make changes to systemd's source code - to make it work on your distribution, unless your code is generic - enough to be generally useful, we are unlikely to merge it. Please - always consider adopting the upstream defaults. If that is not - possible, please maintain the relevant patches downstream. - - Thank you for understanding. diff --git a/doc/TRANSLATORS b/doc/TRANSLATORS deleted file mode 100644 index 873ec7b01c..0000000000 --- a/doc/TRANSLATORS +++ /dev/null @@ -1,27 +0,0 @@ -Notes for translators -===================== - -systemd depends on gettext for multilingual support. -In po/ directory you'll find the needed files. - -POT (Portable Object Template) ------------------------------- -A text file with .pot extension, with all the extracted labels from code. - -To update the template: - -$ cd systemd/ -$ ninja -C build systemd-pot - -To start a new translation: - -$ cd po/ -$ cp systemd.pot .po - -Replace with the two-letters codes of ISO 639 standard. - -PO (Portable Object) --------------------- -A text file with .po extension, with all the available labels and some additional -metadata fields. Any editor is ok, but a good standard is 'poedit', a graphical -application specifically designed for this kind of task. diff --git a/doc/BOOT_LOADER_SPECIFICATION.md b/docs/BOOT_LOADER_SPECIFICATION.md similarity index 100% rename from doc/BOOT_LOADER_SPECIFICATION.md rename to docs/BOOT_LOADER_SPECIFICATION.md diff --git a/doc/CGROUP_DELEGATION.md b/docs/CGROUP_DELEGATION.md similarity index 100% rename from doc/CGROUP_DELEGATION.md rename to docs/CGROUP_DELEGATION.md diff --git a/doc/CODE_QUALITY.md b/docs/CODE_QUALITY.md similarity index 100% rename from doc/CODE_QUALITY.md rename to docs/CODE_QUALITY.md diff --git a/doc/CODING_STYLE b/docs/CODING_STYLE similarity index 100% rename from doc/CODING_STYLE rename to docs/CODING_STYLE diff --git a/.github/CONTRIBUTING.md b/docs/CONTRIBUTING.md similarity index 95% rename from .github/CONTRIBUTING.md rename to docs/CONTRIBUTING.md index 2f266f2934..ea15325fe9 100644 --- a/.github/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -24,8 +24,8 @@ If you discover a security vulnerability, we'd appreciate a non-public disclosur ## Posting Pull Requests * Make sure to post PRs only relative to a very recent git master. -* Follow our [Coding Style](https://raw.githubusercontent.com/systemd/systemd/master/doc/CODING_STYLE) when contributing code. This is a requirement for all code we merge. -* Please make sure to test your change before submitting the PR. See [HACKING](https://raw.githubusercontent.com/systemd/systemd/master/doc/HACKING) for details how to do this. +* Follow our [Coding Style](https://raw.githubusercontent.com/systemd/systemd/master/docs/CODING_STYLE) when contributing code. This is a requirement for all code we merge. +* Please make sure to test your change before submitting the PR. See [HACKING](https://raw.githubusercontent.com/systemd/systemd/master/docs/HACKING) for details how to do this. * Make sure to run the test suite locally, before posting your PR. We use a CI system, meaning we don't even look at your PR, if the build and tests don't pass. * If you need to update the code in an existing PR, force-push into the same branch, overriding old commits with new versions. * After you have pushed a new version, add a comment about the new version (no notification is sent just for the commits, so it's easy to miss the update without an explicit comment). If you are a member of the systemd project on GitHub, remove the `reviewed/needs-rework` label. diff --git a/docs/DISTRO_PORTING.md b/docs/DISTRO_PORTING.md new file mode 100644 index 0000000000..bcb093fbdc --- /dev/null +++ b/docs/DISTRO_PORTING.md @@ -0,0 +1,75 @@ +# Porting systemd To New Distributions + +## HOWTO + +You need to make the follow changes to adapt systemd to your +distribution: + +1. Find the right configure parameters for: + + * `-Drootprefix=` + * `-Dsysvinit-path=` + * `-Dsysvrcnd-path=` + * `-Drc-local=` + * `-Dhalt-local=` + * `-Dloadkeys-path=` + * `-Dsetfont-path=` + * `-Dtty-gid=` + * `-Dntp-servers=` + * `-Ddns-servers=` + * `-Dsupport-url=` + +2. Try it out. + + Play around (as an ordinary user) with + `/usr/lib/systemd/systemd --test --system` for a test run + of systemd without booting. This will read the unit files and + print the initial transaction it would execute during boot-up. + This will also inform you about ordering loops and suchlike. + +## NTP Pool + +By default, systemd-timesyncd uses the Google Public NTP servers +`time[1-4].google.com`, if no other NTP configuration is available. +They serve time that uses a +[leap second smear](https://developers.google.com/time/smear) +and can be up to .5s off from servers that use stepped leap seconds. + +If you prefer to use leap second steps, please register your own +vendor pool at ntp.org and make it the built-in default by +passing `-Dntp-servers=` to meson. Registering vendor +pools is [free](http://www.pool.ntp.org/en/vendors.html). + +Use `-Dntp-servers=` to direct systemd-timesyncd to different fallback +NTP servers. + +## DNS Servers + +By default, systemd-resolved uses the Google Public DNS servers +`8.8.8.8`, `8.8.4.4`, `2001:4860:4860::8888`, `2001:4860:4860::8844` +as fallback, if no other DNS configuration is available. + +Use `-Ddns-servers=` to direct systemd-resolved to different fallback +DNS servers. + +## PAM + +The default PAM config shipped by systemd is really bare bones. +It does not include many modules your distro might want to enable +to provide a more seamless experience. For example, limits set in +`/etc/security/limits.conf` will not be read unless you load `pam_limits`. +Make sure you add modules your distro expects from user services. + +Pass `-Dpamconfdir=no` to meson to avoid installing this file and +instead install your own. + +## Contributing Upstream + +We generally do no longer accept distribution-specific patches to +systemd upstream. If you have to make changes to systemd's source code +to make it work on your distribution, unless your code is generic +enough to be generally useful, we are unlikely to merge it. Please +always consider adopting the upstream defaults. If that is not +possible, please maintain the relevant patches downstream. + +Thank you for understanding. diff --git a/doc/ENVIRONMENT.md b/docs/ENVIRONMENT.md similarity index 100% rename from doc/ENVIRONMENT.md rename to docs/ENVIRONMENT.md diff --git a/doc/HACKING b/docs/HACKING similarity index 96% rename from doc/HACKING rename to docs/HACKING index 182b0bac8c..1778e4822d 100644 --- a/doc/HACKING +++ b/docs/HACKING @@ -7,9 +7,9 @@ Request (PR): https://github.com/systemd/systemd/pull/new Please make sure to follow our Coding Style when submitting patches. See -doc/CODING_STYLE for details. Also have a look at our Contribution Guidelines: +docs/CODING_STYLE for details. Also have a look at our Contribution Guidelines: - https://github.com/systemd/systemd/blob/master/.github/CONTRIBUTING.md + 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 @@ -23,7 +23,7 @@ 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/doc/CODE_QUALITY.md + 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 diff --git a/doc/PORTABLE_SERVICES.md b/docs/PORTABLE_SERVICES.md similarity index 100% rename from doc/PORTABLE_SERVICES.md rename to docs/PORTABLE_SERVICES.md diff --git a/.github/RELEASE.md b/docs/RELEASE.md similarity index 100% rename from .github/RELEASE.md rename to docs/RELEASE.md diff --git a/doc/TRANSIENT-SETTINGS.md b/docs/TRANSIENT-SETTINGS.md similarity index 100% rename from doc/TRANSIENT-SETTINGS.md rename to docs/TRANSIENT-SETTINGS.md diff --git a/docs/TRANSLATORS.md b/docs/TRANSLATORS.md new file mode 100644 index 0000000000..38c2487b90 --- /dev/null +++ b/docs/TRANSLATORS.md @@ -0,0 +1,74 @@ +# Notes for Translators + +systemd depends on the `gettext` package for multilingual support. + +You'll find the i18n files in the `po/` directory. + +The build system (meson/ninja) can be used to generate a template (`*.pot`), +which can be used to create new translations. + +It can also merge the template into the existing translations (`*.po`), to pick +up new strings in need of translation. + +Finally, it is able to compile the translations (to `*.gmo` files), so that +they can be used by systemd software. (This step is also useful to confirm the +syntax of the `*.po` files is correct.) + +# Creating a New Translation + +To create a translation to a language not yet available, start by creating the +initial template: + +``` +$ ninja -C build/ systemd-pot +``` + +This will generate file `po/systemd.pot` in the source tree. + +Then simply copy it to a new ${lang_code}.po file, where +${lang_code} is the two-letter code for a language +(possibly followed by a two-letter uppercase country code), according to the +ISO 639 standard. + +In short: + +
+$ cp po/systemd.pot po/${lang_code}.po
+
+ +Then edit the new po/${lang_code}.po file (for example, +using the `poedit` GUI editor.) + +# Updating an Existing Translation + +Start by updating the `*.po` files from the latest template: + +``` +$ ninja -C build/ systemd-update-po +``` + +This will touch all the `*.po` files, so you'll want to pay attention when +creating a git commit from this change, to only include the one translation +you're actually updating. + +Edit the `*.po` file, looking for empty translations and translations marked as +"fuzzy" (which means the merger found a similar message that needs to be +reviewed as it's expected not to match exactly.) + +You can use any text editor to update the `*.po` files, but a good choice is +the `poedit` editor, a graphical application specifically designed for this +purpose. + +Once you're done, create a git commit for the update of the `po/*.po` file you +touched. Remember to undo the changes to the other `*.po` files (for instance, +using `git checkout -- po/` after you commit the changes you do want to keep.) + +# Recompiling Translations + +You can recompile the `*.po` files using the following command: + +``` +$ ninja -C build/ systemd-gmo +``` + +The resulting files will be saved in the `build/po/` directory. diff --git a/doc/UIDS-GIDS.md b/docs/UIDS-GIDS.md similarity index 100% rename from doc/UIDS-GIDS.md rename to docs/UIDS-GIDS.md diff --git a/doc/sysvinit/README.in b/docs/sysvinit/README.in similarity index 100% rename from doc/sysvinit/README.in rename to docs/sysvinit/README.in diff --git a/doc/sysvinit/meson.build b/docs/sysvinit/meson.build similarity index 100% rename from doc/sysvinit/meson.build rename to docs/sysvinit/meson.build diff --git a/doc/var-log/README.in b/docs/var-log/README.in similarity index 100% rename from doc/var-log/README.in rename to docs/var-log/README.in diff --git a/doc/var-log/meson.build b/docs/var-log/meson.build similarity index 100% rename from doc/var-log/meson.build rename to docs/var-log/meson.build diff --git a/meson.build b/meson.build index 7ffe61246a..d4d6f01377 100644 --- a/meson.build +++ b/meson.build @@ -2746,8 +2746,8 @@ subdir('network') subdir('man') subdir('shell-completion/bash') subdir('shell-completion/zsh') -subdir('doc/sysvinit') -subdir('doc/var-log') +subdir('docs/sysvinit') +subdir('docs/var-log') # FIXME: figure out if the warning is true: # https://github.com/mesonbuild/meson/wiki/Reference-manual#install_subdir @@ -2763,13 +2763,13 @@ install_data('LICENSE.GPL2', 'LICENSE.LGPL2.1', 'NEWS', 'README', - 'doc/CODING_STYLE', - 'doc/DISTRO_PORTING', - 'doc/ENVIRONMENT.md', - 'doc/HACKING', - 'doc/TRANSIENT-SETTINGS.md', - 'doc/TRANSLATORS', - 'doc/UIDS-GIDS.md', + 'docs/CODING_STYLE', + 'docs/DISTRO_PORTING.md', + 'docs/ENVIRONMENT.md', + 'docs/HACKING', + 'docs/TRANSIENT-SETTINGS.md', + 'docs/TRANSLATORS.md', + 'docs/UIDS-GIDS.md', 'src/libsystemd/sd-bus/GVARIANT-SERIALIZATION', install_dir : docdir)