shaba/systemd-stable
1
1
Fork 0
mirror of https://github.com/systemd/systemd-stable.git synced 2024-12-22 13:33:56 +03:00
Code

docs/CONTRIBUTING: strenghten language about ABI stability, fix links, other tweaks

Browse Source 
The text made it sound like breaking ABI in libsystemd is allowed with good reasons.
In fact, we plan never to do this, so make the language stronger.

Also remind people about distro forums for reporting bugs. Those are probably a
better place than systemd-devel for new users.

Also, add some missing articles and apostrophes, fix URLs, remove repeated phrases,
etc.
This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2022-09-30 17:26:34 +02:00
parent 0d73603b25
commit 868e6ce65c
1 changed files with 11 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
docs/CONTRIBUTING.md
View File

@ -11,7 +11,7 @@ We welcome contributions from everyone. However, please follow the following gui
## Filing Issues
* We use [GitHub Issues](https://github.com/systemd/systemd/issues) **exclusively** for tracking **bugs** and **feature** **requests** (RFEs) of systemd. If you are looking for help, please contact [systemd-devel mailing list](https://lists.freedesktop.org/mailman/listinfo/systemd-devel) instead.
* We use [GitHub Issues](https://github.com/systemd/systemd/issues) **exclusively** for tracking **bugs** and **feature** **requests** (RFEs) of systemd. If you are looking for help, please try the forums of your distribution first, or [systemd-devel mailing list](https://lists.freedesktop.org/mailman/listinfo/systemd-devel) for general questions about systemd.
* We only track bugs in the **two** **most** **recently** **released** (non-rc) **versions** of systemd in the GitHub Issue tracker. If you are using an older version of systemd, please contact your distribution's bug tracker instead (see below). See [GitHub Release Page](https://github.com/systemd/systemd/releases) for the list of most recent releases.
* When filing a feature request issue (RFE), please always check first if the newest upstream version of systemd already implements the feature, and whether there's already an issue filed for your feature by someone else.
* When filing an issue, specify the **systemd** **version** you are experiencing the issue with. Also, indicate which **distribution** you are using.
@ -34,10 +34,10 @@ See [reporting of security vulnerabilities](SECURITY.md).
* Make sure to post PRs only relative to a recent tip of the `main` branch.
* Follow our [Coding Style](CODING_STYLE.md) when contributing code. This is a requirement for all code we merge.
* Please make sure to test your change before submitting the PR. See the [Hacking guide](HACKING.md) for details on 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.
* 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 explaining the latest changes. If you are a member of the systemd project on GitHub, remove the `reviewed/needs-rework`/`ci-fails/needs-rework`/`needs-rebase` labels.
* If you are copying existing code from another source (eg: a compat header), please make sure the license is compatible with LGPL-2.1-or-later. If the license is not LGPL-2.1-or-later, please add a note to LICENSES/README.md.
* If you are copying existing code from another source (eg: a compat header), please make sure the license is compatible with `LGPL-2.1-or-later`. If the license is not `LGPL-2.1-or-later`, please add a note to [`LICENSES/README.md`](https://github.com/systemd/systemd/blob/main/LICENSES/README.md).
* If the pull request stalls without review, post a ping in a comment after some time has passed. We are always short on reviewer time, and pull requests which haven't seen any recent activity can be easily forgotten.
## Reviewing Pull Requests
@ -65,14 +65,13 @@ Thank you very much for your contributions!
# Backward Compatibility And External Dependencies
We strive to keep backward compatibility where possible and reasonable. The following are general guidelines, not hard
rules, and case-by-case exceptions might be applied at the discretion of the maintainers. The current set of build time
and runtime dependencies are documented in the [README](../README).
rules, and case-by-case exceptions might be applied at the discretion of the maintainers. The current set of build-time
and runtime dependencies are documented in the [README](https://github.com/systemd/systemd/blob/main/README).
## New features
It is fine for new features/functionality/tools/daemons to require bleeding edge external dependencies, provided there
are runtime and build time graceful fallbacks (e.g.: daemon will not be built, runtime functionality will be skipped with
clear log message).
are runtime and build-time graceful fallbacks (e.g.: a daemon will not be built, runtime functionality will be skipped with a clear log message).
In case a new feature is added to both `systemd` and one of its dependencies, we expect the corresponding feature code to
be merged upstream in the dependency before accepting our side of the implementation.
Making use of new kernel syscalls can be achieved through compat wrappers in our tree (see: `src/basic/missing_syscall_def.h`),
@ -80,8 +79,8 @@ and does not need to wait for glibc support.
## External Build/Runtime Dependencies
It is often tempting to bump external dependencies minimum versions to cut cruft, and in general it's an essential part
of the maintenance process. But as a generic rule, existing dependencies should not be bumped without very strong
It is often tempting to bump external dependencies' minimum versions to cut cruft, and in general it's an essential part
of the maintenance process. But as a general rule, existing dependencies should not be bumped without strong
reasons. When possible, we try to keep compatibility with the most recent LTS releases of each mainstream distribution
for optional components, and with all currently maintained (i.e.: not EOL) LTS releases for core components. When in
doubt, ask before committing time to work on contributions if it's not clear that cutting support would be obviously
@ -94,14 +93,13 @@ functionality or optional features, but very strong reasons should be required f
functionality, especially for core components. It is not uncommon, for example, for embedded systems to be stuck on older
kernel versions due to hardware requirements, so do not assume everybody is running with latest and greatest at all times.
In general, [currently maintained LTS branches](https://www.kernel.org/category/releases.html) should keep being supported
for existing functionality, especially for core components.
for existing functionality.
## `libsystemd.so`
`libsystemd.so` is a shared public library, so breaking ABI/API compatibility creates a lot of work for its users, and should
always be avoided apart from the most extreme circumstances. For example, always add a new interface instead of modifying
`libsystemd.so` is a shared public library, so breaking ABI/API compatibility would create lot of work for everyone, and is not allowed. Instead, always add a new interface instead of modifying
the signature of an existing function. It is fine to mark an interface as deprecated to gently nudge users toward a newer one,
but in general support for the old one should be maintained whenever possible.
but support for the old one must be maintained.
Symbol versioning and the compiler's deprecated attribute should be used when managing the lifetime of a public interface.
## `libudev.so`