Notes/notes-service/vendor/libc/CONTRIBUTING.md

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 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¹ , 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!

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. 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.

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 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:

   /// Constants may change across releases. See the [usage guidelines](crate#usage-guidelines)
   /// for details.
   

4. Run tests locally, following the directions at 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!

---

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)]. ↩︎