]>
Commit | Line | Data |
---|---|---|
c3e270f4 FB |
1 | --- |
2 | title: Contributing | |
4cdca0af | 3 | category: Contributing |
b41a3f66 | 4 | layout: default |
0aff7b75 | 5 | SPDX-License-Identifier: LGPL-2.1-or-later |
c3e270f4 FB |
6 | --- |
7 | ||
cc5fddef LP |
8 | # Contributing |
9 | ||
945c6e7c | 10 | We welcome contributions from everyone. However, please follow the following guidelines when posting a GitHub Pull Request or filing a GitHub Issue on the systemd project: |
cc5fddef LP |
11 | |
12 | ## Filing Issues | |
13 | ||
0d8926b1 | 14 | * We use [GitHub Issues](https://github.com/systemd/systemd/issues) **exclusively** for tracking **bugs** and **feature** **requests** (RFEs) of systemd. |
15 | 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. | |
16 | * We only track bugs in the **two** **most** **recently** **released** (non-rc) **versions** of systemd in the GitHub Issue tracker. | |
17 | If you are using an older version of systemd, please contact your distribution's bug tracker instead (see below). | |
18 | See [GitHub Release Page](https://github.com/systemd/systemd/releases) for the list of most recent releases. | |
19 | * When filing a feature request issue (RFE), please always check first if the newest upstream version of systemd already implements the feature, | |
20 | and whether there's already an issue filed for your feature by someone else. | |
945c6e7c | 21 | * When filing an issue, specify the **systemd** **version** you are experiencing the issue with. Also, indicate which **distribution** you are using. |
cc5fddef LP |
22 | * Please include an explanation how to reproduce the issue you are pointing out. |
23 | ||
945c6e7c | 24 | Following these guidelines makes it easier for us to process your issue, and ensures we won't close your issue right-away for being misfiled. |
cc5fddef | 25 | |
75d96e22 | 26 | ### Older downstream versions |
efe05392 | 27 | |
75d96e22 | 28 | For older versions that are still supported by your distribution please use respective downstream tracker: |
efe05392 | 29 | |
75d96e22 | 30 | * **Fedora** - [bugzilla](https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora&component=systemd) |
e868f5ef | 31 | * **RHEL/CentOS stream** - [Jira](https://issues.redhat.com/secure/CreateIssueDetails!init.jspa?pid=12332745&issuetype=1&components=12380515&priority=10300) or [contribute to systemd-rhel @GitHub](https://github.com/redhat-plumbers#systemd) |
75d96e22 LN |
32 | * **Debian** - [bugs.debian.org](https://bugs.debian.org/cgi-bin/pkgreport.cgi?pkg=systemd) |
33 | ||
c2205a0d ZJS |
34 | ## Security vulnerability reports |
35 | ||
0d592a5e | 36 | See [reporting of security vulnerabilities](/SECURITY). |
c2205a0d | 37 | |
cc5fddef LP |
38 | ## Posting Pull Requests |
39 | ||
d331f484 | 40 | * Make sure to post PRs only relative to a recent tip of the `main` branch. |
0d592a5e FS |
41 | * Follow our [Coding Style](/CODING_STYLE) when contributing code. This is a requirement for all code we merge. |
42 | * Please make sure to test your change before submitting the PR. See the [Hacking guide](/HACKING) for details on how to do this. | |
868e6ce6 | 43 | * 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. |
a87c45a8 | 44 | * If you need to update the code in an existing PR, force-push into the same branch, overriding old commits with new versions. |
0d8926b1 | 45 | * After you have pushed a new version, add a comment explaining the latest changes. |
46 | If you are a member of the systemd project on GitHub, remove the `reviewed/needs-rework`/`ci-fails/needs-rework`/`needs-rebase` labels. | |
47 | * 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`. | |
48 | 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). | |
49 | * If the pull request stalls without review, post a ping in a comment after some time has passed. | |
50 | We are always short on reviewer time, and pull requests which haven't seen any recent activity can be easily forgotten. | |
51 | * Github will automatically add the `please-review` label when a pull request is opened or updated. | |
52 | If you need more information after a review, you can comment `/please-review` on the pull request to have Github add the `please-review` label to the pull request. | |
cc5fddef | 53 | |
3efadceb ZJS |
54 | ## Reviewing Pull Requests |
55 | ||
56 | * See [filtered list of pull requests](https://github.com/systemd/systemd/pulls?q=is%3Aopen+is%3Apr+-label%3A%22reviewed%2Fneeds-rework+%F0%9F%94%A8%22+-label%3Aneeds-rebase+-label%3Agood-to-merge%2Fwith-minor-suggestions+-label%3A%22good-to-merge%2Fwaiting-for-ci+%F0%9F%91%8D%22+-label%3Apostponed+-label%3A%22needs-reporter-feedback+%E2%9D%93%22+-label%3A%22dont-merge+%F0%9F%92%A3%22+-label%3A%22ci-fails%2Fneeds-rework+%F0%9F%94%A5%22+sort%3Aupdated-desc) for requests that are ready for review. | |
57 | * After performing a review, set | |
58 | ||
efe05392 JM |
59 | * `reviewed/needs-rework` if the pull request needs significant changes |
60 | * `ci-fails/needs-rework` if the automatic tests fail and the failure is relevant to the pull request | |
61 | * `ci-failure-appears-unrelated` if the test failures seem irrelevant | |
62 | * `needs-rebase` if the pull request needs a rebase because of conflicts | |
63 | * `good-to-merge/waiting-for-ci` if the pull request should be merged without further review | |
64 | * `good-to-merge/with-minor-suggestions` if the pull request should be merged after an update without going through another round of reviews | |
3efadceb ZJS |
65 | |
66 | Unfortunately only members of the `systemd` organization on github can change labels. | |
67 | If your pull request is mislabeled, make a comment in the pull request and somebody will fix it. | |
68 | Reviews from non-members are still welcome. | |
69 | ||
cc5fddef LP |
70 | ## Final Words |
71 | ||
945c6e7c | 72 | We'd like to apologize in advance if we are not able to process and reply to your issue or PR right-away. We have a lot of work to do, but we are trying our best! |
cc5fddef LP |
73 | |
74 | Thank you very much for your contributions! | |
ea7ded75 LB |
75 | |
76 | # Backward Compatibility And External Dependencies | |
77 | ||
0d8926b1 | 78 | We strive to keep backward compatibility where possible and reasonable. |
79 | The following are general guidelines, not hard rules, and case-by-case exceptions might be applied at the discretion of the maintainers. | |
80 | The current set of build-time and runtime dependencies are documented in the [README](https://github.com/systemd/systemd/blob/main/README). | |
ea7ded75 LB |
81 | |
82 | ## New features | |
83 | ||
84 | It is fine for new features/functionality/tools/daemons to require bleeding edge external dependencies, provided there | |
868e6ce6 | 85 | 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). |
ea7ded75 LB |
86 | In case a new feature is added to both `systemd` and one of its dependencies, we expect the corresponding feature code to |
87 | be merged upstream in the dependency before accepting our side of the implementation. | |
88 | Making use of new kernel syscalls can be achieved through compat wrappers in our tree (see: `src/basic/missing_syscall_def.h`), | |
89 | and does not need to wait for glibc support. | |
90 | ||
91 | ## External Build/Runtime Dependencies | |
92 | ||
868e6ce6 ZJS |
93 | It is often tempting to bump external dependencies' minimum versions to cut cruft, and in general it's an essential part |
94 | of the maintenance process. But as a general rule, existing dependencies should not be bumped without strong | |
ea7ded75 LB |
95 | reasons. When possible, we try to keep compatibility with the most recent LTS releases of each mainstream distribution |
96 | for optional components, and with all currently maintained (i.e.: not EOL) LTS releases for core components. When in | |
97 | doubt, ask before committing time to work on contributions if it's not clear that cutting support would be obviously | |
98 | acceptable. | |
99 | ||
100 | ## Kernel Requirements | |
101 | ||
102 | Same principles as with other dependencies should be applied. It is fine to require newer kernel versions for additional | |
103 | functionality or optional features, but very strong reasons should be required for breaking compatibility for existing | |
104 | functionality, especially for core components. It is not uncommon, for example, for embedded systems to be stuck on older | |
105 | kernel versions due to hardware requirements, so do not assume everybody is running with latest and greatest at all times. | |
106 | In general, [currently maintained LTS branches](https://www.kernel.org/category/releases.html) should keep being supported | |
868e6ce6 | 107 | for existing functionality. |
ea7ded75 LB |
108 | |
109 | ## `libsystemd.so` | |
110 | ||
0d8926b1 | 111 | `libsystemd.so` is a shared public library, so breaking ABI/API compatibility would create lot of work for everyone, and is not allowed. |
112 | Instead, always add a new interface instead of modifying the signature of an existing function. | |
113 | It is fine to mark an interface as deprecated to gently nudge users toward a newer one, but support for the old one must be maintained. | |
ea7ded75 LB |
114 | Symbol versioning and the compiler's deprecated attribute should be used when managing the lifetime of a public interface. |
115 | ||
116 | ## `libudev.so` | |
117 | ||
118 | `libudev.so` is a shared public library, and is still maintained, but should not gain new symbols at this point. |