|
| 1 | +# Contributing to `libc` |
| 2 | + |
| 3 | +Welcome! If you are reading this document, it means you are interested in |
| 4 | +contributing to the `libc` crate. |
| 5 | + |
| 6 | +## v1.0 Roadmap |
| 7 | + |
| 8 | +`libc` has two active branches: `main` and `libc-0.2`. `main` is for active |
| 9 | +development of the upcoming v1.0 release, and should be the target of all pull |
| 10 | +requests. `libc-0.2` is for updates to the currently released version. |
| 11 | + |
| 12 | +If a pull request to `main` is a good candidate for inclusion in an `0.2.x` |
| 13 | +release, include `@rustbot label stable-nominated` in a comment to propose this. |
| 14 | +Good candidates will usually meet the following: |
| 15 | + |
| 16 | +1. The included changes are non-breaking. |
| 17 | +2. The change applies cleanly to both branches. |
| 18 | +3. There is a usecase that justifies inclusion in a stable release (all |
| 19 | + additions should always have a usecase, hopefully). |
| 20 | + |
| 21 | +Once a `stable-nominated` PR targeting `main` has merged, it can be cherry |
| 22 | +picked to the `libc-0.2` branch. A maintainer will likely do these cherry picks |
| 23 | +in a batch. |
| 24 | + |
| 25 | +Alternatively, you can start this process yourself by creating a new branch |
| 26 | +based on `libc-0.2` and running `git cherry-pick -xe commit-sha-on-main` |
| 27 | +(`git |
| 28 | +cherry-pick -xe start-sha^..end-sha` if a range of commits is needed). |
| 29 | +`git` will automatically add the "cherry picked from commit" note, but try to |
| 30 | +add a backport note so the original PR gets crosslinked: |
| 31 | + |
| 32 | +``` |
| 33 | +# ... original commit message ... |
| 34 | +
|
| 35 | +(backport <https://github.com/rust-lang/libc/pull/1234>) # add manually |
| 36 | +(cherry picked from commit 104b6a4ae31c726814c36318dc718470cc96e167) # added by git |
| 37 | +``` |
| 38 | + |
| 39 | +Once the cherry-pick is complete, open a PR targeting `libc-0.2`. |
| 40 | + |
| 41 | +See the [tracking issue](https://github.com/rust-lang/libc/issues/3248) for |
| 42 | +details. |
| 43 | + |
| 44 | +## Adding an API |
| 45 | + |
| 46 | +Want to use an API which currently isn't bound in `libc`? It's quite easy to add |
| 47 | +one! |
| 48 | + |
| 49 | +The internal structure of this crate is designed to minimize the number of |
| 50 | +`#[cfg]` attributes in order to easily be able to add new items which apply to |
| 51 | +all platforms in the future. As a result, the crate is organized hierarchically |
| 52 | +based on platform. Each module has a number of `#[cfg]`'d children, but only one |
| 53 | +is ever actually compiled. Each module then reexports all the contents of its |
| 54 | +children. |
| 55 | + |
| 56 | +This means that for each platform that libc supports, the path from a leaf |
| 57 | +module to the root will contain all bindings for the platform in question. |
| 58 | +Consequently, this indicates where an API should be added! Adding an API at a |
| 59 | +particular level in the hierarchy means that it is supported on all the child |
| 60 | +platforms of that level. For example, when adding a Unix API it should be added |
| 61 | +to `src/unix/mod.rs`, but when adding a Linux-only API it should be added to |
| 62 | +`src/unix/linux_like/linux/mod.rs`. |
| 63 | + |
| 64 | +If you're not 100% sure at what level of the hierarchy an API should be added |
| 65 | +at, fear not! This crate has CI support which tests any binding against all |
| 66 | +platforms supported, so you'll see failures if an API is added at the wrong |
| 67 | +level or has different signatures across platforms. |
| 68 | + |
| 69 | +New symbol(s) (i.e. functions, constants etc.) should also be added to the |
| 70 | +symbols list(s) found in the `libc-test/semver` directory. These lists keep |
| 71 | +track of what symbols are public in the libc crate and ensures they remain |
| 72 | +available between changes to the crate. If the new symbol(s) are available on |
| 73 | +all supported Unixes it should be added to `unix.txt` list<sup>1</sup>, |
| 74 | +otherwise they should be added to the OS specific list(s). |
| 75 | + |
| 76 | +With that in mind, the steps for adding a new API are: |
| 77 | + |
| 78 | +1. Determine where in the module hierarchy your API should be added. |
| 79 | +2. Add the API, including adding new symbol(s) to the semver lists. |
| 80 | +3. Send a PR to this repo. |
| 81 | +4. Wait for CI to pass, fixing errors. |
| 82 | +5. Wait for a merge! |
| 83 | + |
| 84 | +<sup>1</sup>: Note that this list has nothing to do with any Unix or Posix |
| 85 | +standard, it's just a list shared among all OSs that declare `#[cfg(unix)]`. |
| 86 | + |
| 87 | +## Test before you commit |
| 88 | + |
| 89 | +We have two automated tests running on |
| 90 | +[GitHub Actions](https://github.com/rust-lang/libc/actions): |
| 91 | + |
| 92 | +1. [`libc-test`](https://github.com/gnzlbg/ctest) |
| 93 | + - `cd libc-test && cargo test` |
| 94 | + - Use the `skip_*()` functions in `build.rs` if you really need a workaround. |
| 95 | +2. Style checker |
| 96 | + - [`./ci/style.sh`](https://github.com/rust-lang/libc/blob/main/ci/style.sh) |
| 97 | + |
| 98 | +## Breaking change policy |
| 99 | + |
| 100 | +Sometimes an upstream adds a breaking change to their API e.g. removing outdated |
| 101 | +items, changing the type signature, etc. And we probably should follow that |
| 102 | +change to build the `libc` crate successfully. It's annoying to do the |
| 103 | +equivalent of semver-major versioning for each such change. Instead, we mark the |
| 104 | +item as deprecated and do the actual change after a certain period. The steps |
| 105 | +are: |
| 106 | + |
| 107 | +1. Add `#[deprecated(since = "", note="")]` attribute to the item. |
| 108 | + - The `since` field should have a next version of `libc` (e.g., if the current |
| 109 | + version is `0.2.1`, it should be `0.2.2`). |
| 110 | + - The `note` field should have a reason to deprecate and a tracking issue to |
| 111 | + call for comments (e.g., "We consider removing this as the upstream removed |
| 112 | + it. If you're using it, please comment on #XXX"). |
| 113 | +2. If we don't see any concerns for a while, do the change actually. |
| 114 | + |
| 115 | +## Supported target policy |
| 116 | + |
| 117 | +When Rust removes a support for a target, the libc crate also may remove the |
| 118 | +support at any time. |
| 119 | + |
| 120 | +## Releasing your change to crates.io |
| 121 | + |
| 122 | +This repository uses [release-plz] to handle releases. Once your pull request |
| 123 | +has been merged, a maintainer just needs to verify the generated changelog, then |
| 124 | +merge the bot's release PR. This will automatically publish to crates.io! |
| 125 | + |
| 126 | +[release-plz]: https://github.com/MarcoIeni/release-plz |
0 commit comments