summaryrefslogtreecommitdiff
path: root/docs/PORTABILITY_AND_STABILITY.md
diff options
context:
space:
mode:
authorZbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl>2020-01-12 18:32:40 +0100
committerZbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl>2020-01-12 18:54:17 +0100
commitef0bea8cf4f1615df0ec47a7ec854862841ec2cc (patch)
treea9cf4e7446058d2185fb103b87b695dd853188a6 /docs/PORTABILITY_AND_STABILITY.md
parentb2eea3dc325e8bcf680e09e08488600380334000 (diff)
downloadsystemd-ef0bea8cf4f1615df0ec47a7ec854862841ec2cc.tar.gz
docs: say that dbus api is stable (but list various caveats)
I removed the part about sysv compat, because that has already been removed and we don't make any use of conditional dbus interfaces afaict.
Diffstat (limited to 'docs/PORTABILITY_AND_STABILITY.md')
-rw-r--r--docs/PORTABILITY_AND_STABILITY.md2
1 files changed, 1 insertions, 1 deletions
diff --git a/docs/PORTABILITY_AND_STABILITY.md b/docs/PORTABILITY_AND_STABILITY.md
index ee771592b6..ceb82dba3c 100644
--- a/docs/PORTABILITY_AND_STABILITY.md
+++ b/docs/PORTABILITY_AND_STABILITY.md
@@ -14,11 +14,11 @@ The stable interfaces are:
* **The command line interface** of `systemd`, `systemctl`, `loginctl`, `journalctl`, and all other command line utilities installed in `$PATH` and documented in a man page. We will make sure that scripts invoking these commands will continue to work with future versions of systemd. Note however that the output generated by these commands is generally not included in the promise, unless it is documented in the man page. Example: the output of `systemctl status` is not stable, but that of `systemctl show` is, because the former is intended to be human readable and the latter computer readable, and this is documented in the man page.
* **The protocol spoken on the socket referred to by $NOTIFY_SOCKET**, as documented in (sd_notify(3))[https://www.freedesktop.org/software/systemd/man/sd_notify.html].
* Some of the **"special" unit names** and their semantics. To be precise the ones that are necessary for normal services, and not those required only for early boot and late shutdown, with very few exceptions. To list them here: `basic.target`, `shutdown.target`, `sockets.target`, `network.target`, `getty.target`, `graphical.target`, `multi-user.target`, `rescue.target`, `emergency.target`, `poweroff.target`, `reboot.target`, `halt.target`, `runlevel[1-5].target`.
+* **The D-Bus interfaces of the main service daemon and other daemons**. We try to always preserve backwards compatiblity, and intentational breakage is never introduced. Nevertheless, when we find bugs that mean that the existing interface was not useful, or when the implementation did something different than stated by the documentation and the implemented behaviour is not useful, we will fix the implementation and thus introduce a change in behaviour. But the API (parameter counts and types) is never changed, and existing attributes and methods will not be removed.
* For a more comprehensive and authoritative list, consult the chart below.
The following interfaces will not necessarily be kept stable for now, but we will eventually make a stability promise for these interfaces too. In the meantime we will however try to keep breakage of these interfaces at a minimum:
-* **The D-Bus interfaces of the main service daemon** (!) [ An additional restriction applies here: functionality we consider legacy might not be available based on compile-time options, such as SysV support, libwrap support and similar. Apps should not assume properties and methods related to this functionality are unconditionally available in the D-Bus interfaces. ]
* **The set of states of the various state machines used in systemd**, e.g. the high-level unit states inactive, active, deactivating, and so on, as well (and in particular) the low-level per-unit states.
* **All "special" units that aren't listed above**.