153 lines
6.3 KiB
Markdown
153 lines
6.3 KiB
Markdown
# Contributing to `libc`
|
|
|
|
Welcome! If you are reading this document, it means you are interested in
|
|
contributing to the `libc` crate.
|
|
|
|
## v1.0 Roadmap
|
|
|
|
`libc` has two active branches: `main` and `libc-0.2`. `main` is for active
|
|
development of the upcoming v1.0 release, and should be the target of all pull
|
|
requests. `libc-0.2` is for updates to the currently released version.
|
|
|
|
If a pull request to `main` is a good candidate for inclusion in an `0.2.x`
|
|
release, include `@rustbot label stable-nominated` in a comment to propose this.
|
|
Almost everything should be included in stable, unless it involves breaking
|
|
changes.
|
|
|
|
Once a `stable-nominated` PR targeting `main` has merged, it can be cherry
|
|
picked to the `libc-0.2` branch. A maintainer will likely do these cherry picks
|
|
in a batch before a release, so there is no need for any action as a PR author.
|
|
|
|
When cherry picking, run the following after branching from `libc-0.2`:
|
|
`git cherry-pick -xe commit-sha-on-main` (or `git cherry-pick -xe
|
|
start-sha^..end-sha` if a range of commits is needed). `git` will automatically
|
|
add the "cherry picked from commit" note, but try to add a backport note so the
|
|
original PR gets crosslinked:
|
|
|
|
```
|
|
# ... original commit message ...
|
|
|
|
(backport <https://github.com/rust-lang/libc/pull/1234>) # add manually
|
|
(cherry picked from commit 104b6a4ae31c726814c36318dc718470cc96e167) # added by git
|
|
```
|
|
|
|
Cherry pick PRs can then target `libc-0.2`.
|
|
|
|
See the [tracking issue](https://github.com/rust-lang/libc/issues/3248) for
|
|
details.
|
|
|
|
## Adding an API
|
|
|
|
Want to use an API which currently isn't bound in `libc`? It's quite easy to add
|
|
one!
|
|
|
|
If you are adding API for a header that doesn't already have some bindings,
|
|
create a new file in the appropriate location in `src/new`. These modules should
|
|
approximately match source trees: try to follow the patterns that are there but
|
|
don't hesitate to ask maintainers if guidance is needed.
|
|
|
|
If some bindings for the relevant header has already been added outside of
|
|
`src/new`, it is fine to extend what already exists. Everything outside of
|
|
`src/new` uses a hierarchial structure: a single path from root to a leaf node
|
|
represents a single platform, and adding API at a given level will make it
|
|
available on all children.
|
|
|
|
We are currently in a reorganization process, moving from the hierarchial
|
|
structure to the source-mapped structure in `src/new`.
|
|
|
|
New items (i.e. functions, constants etc.) should also be added to the symbol
|
|
list(s) found in the `libc-test/semver` directory. These lists track of what
|
|
API is public in the libc crate and ensures they remain available between
|
|
changes to the crate. If the new symbol(s) are available on all supported Unixes
|
|
it should be added to `unix.txt` list[^1], otherwise they should be added to the
|
|
OS-specific list(s).
|
|
|
|
With that in mind, the steps for adding a new API are:
|
|
|
|
1. Determine where to add your API.
|
|
2. Add the API, including adding new symbol(s) to the semver lists.
|
|
3. Send a PR to this repo.
|
|
4. Wait for CI to pass, fixing errors.
|
|
5. Wait for a merge!
|
|
|
|
[^1]: Note that this list has nothing to do with any Unix or Posix standard,
|
|
it's just a list shared among all OSs that declare `#[cfg(unix)]`.
|
|
|
|
## Test before you commit
|
|
|
|
There are a few relevant tests in `libc`:
|
|
|
|
1. `libc-test` is the main test suite. This can be run locally with `cargo test
|
|
--workspace`.
|
|
|
|
If needed, the `skip_*()` functions in `libc-test/build.rs` can be used to
|
|
skip testing specific API.
|
|
2. Style checker and formatter, located at [`./ci/style.py`][style-py]. Running
|
|
this also invokes the code formatter. (This also formats code within macros,
|
|
which `cargo fmt` won't do.)
|
|
3. `ci/verify-build.py`, which checks the build on a wide range of targets.
|
|
Typically there is no need to run this locally.
|
|
|
|
[style-py]: https://github.com/rust-lang/libc/blob/main/ci/style.py
|
|
|
|
## Submitting a Pull Request
|
|
|
|
When you submit a PR, please follow these guidelines to give your PR the best
|
|
chance of being accepted:
|
|
|
|
1. All new API should be added to `libc-test/semver`, which makes sure it
|
|
doesn't get removed in the future.
|
|
2. All changes *must* have permalink to headers in commit messages. See
|
|
[Source links](#source-links) below for more details.
|
|
3. For any constants that are expected to change, e.g. `*LAST` or `*MAX`, try to
|
|
add the following doc comment:
|
|
|
|
```rust
|
|
/// Constants may change across releases. See the [usage guidelines](crate#usage-guidelines)
|
|
/// for details.
|
|
```
|
|
5. Run tests locally, following the directions at
|
|
[Test before you commit](test-before-you-commit). This is especially relevant
|
|
for platforms that aren't tested on CI.
|
|
|
|
### Source links
|
|
|
|
Please include permalinks to headers in commit messages for all API changes.
|
|
Common sources include:
|
|
|
|
* Linux uapi: https://github.com/torvalds/linux/tree/master/include/uapi
|
|
* Glibc: https://sourceware.org/git/?p=glibc.git;a=tree
|
|
* Musl: https://github.com/kraj/musl (original is https://git.musl-libc.org/cgit/musl/tree/)
|
|
* Apple XNU: https://github.com/apple-oss-distributions/xnu, libc https://github.com/apple-oss-distributions/Libc/tree/main/include
|
|
* Android: https://cs.android.com/android/platform/superproject/main
|
|
* FreeBSD: https://github.com/freebsd/freebsd-src/tree/main/lib/libc
|
|
* Illumos: https://github.com/illumos/illumos-gate/tree/master/usr/src/lib/libc
|
|
* Fuchsia: https://cs.opensource.google/fuchsia/fuchsia/+/main:zircon/
|
|
|
|
After navigating to the relevant file and selecting relevant lines, get a
|
|
permalink. On GitHub this is available by clicking the triple dots and
|
|
selecting "copy permalink", and on the Android and Fuchsia source viewers
|
|
this is available via l-r (links->commit).
|
|
|
|
If sources are closed, link to documentation or paste relevant C declarations.
|
|
|
|
(Including this information in the PR description is fine too, commit messages
|
|
are preferred because they become part of history.)
|
|
|
|
## Breaking change policy
|
|
|
|
See `src/lib.rs` for details.
|
|
|
|
## Supported target policy
|
|
|
|
When Rust removes a support for a target, the libc crate also may remove the
|
|
support at any time. MSRV may be different for different targets.
|
|
|
|
## Releasing change to crates.io
|
|
|
|
This repository uses [release-plz] to handle releases. Once your pull request
|
|
has been merged, a maintainer needs to create the changelog and merge a PR
|
|
bumping the version. This will automatically publish to crates.io!
|
|
|
|
[release-plz]: https://github.com/MarcoIeni/release-plz
|