Merge pull request #10037 from filbranden/docs2

Moving docs around and starting conversion to Markdown
This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2018-09-09 21:01:17 +02:00 committed by GitHub
commit 3c83f15967
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
21 changed files with 164 additions and 113 deletions

View File

@ -8,7 +8,7 @@ about: A report of an error in a recent systemd version
> ...
<!-- **NOTE:** Do not submit bug reports about anything but the two most recently released systemd versions upstream! -->
<!-- For older version please use distribution trackers (see https://github.com/systemd/systemd/blob/master/.github/CONTRIBUTING.md#filing-issues). -->
<!-- For older version please use distribution trackers (see https://github.com/systemd/systemd/blob/master/docs/CONTRIBUTING.md#filing-issues). -->
**Used distribution**
> …

View File

@ -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.

View File

@ -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 <YOUR-LANG-CODE>.po
Replace <YOUR-LANG-CODE> 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.

View File

@ -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.

75
docs/DISTRO_PORTING.md Normal file
View File

@ -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.

View File

@ -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

74
docs/TRANSLATORS.md Normal file
View File

@ -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 <code><i>${lang_code}</i>.po</code> file, where
<code><i>${lang_code}</i></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:
<pre>
$ cp po/systemd.pot po/<i>${lang_code}</i>.po
</pre>
Then edit the new <code>po/<i>${lang_code}</i>.po</code> 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.

View File

@ -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)