Merge pull request #4071 from tgross35/docs-sync

Sync docs from 0.2 to main

Author: tgross35

CONTRIBUTING.md

@@ -1,7 +1,7 @@
 # Contributing to `libc`
 
-Welcome! If you are reading this document, it means you are interested in contributing
-to the `libc` crate.
+Welcome! If you are reading this document, it means you are interested in
+contributing to the `libc` crate.
 
 ## v1.0 Roadmap
 
@@ -19,14 +19,15 @@ Good candidates will usually meet the following:
    additions should always have a usecase, hopefully).
 
 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.
+picked to the `libc-0.2` branch. A maintainer will likely do these cherry picks
+in a batch.
 
 Alternatively, you can start this process yourself by creating a new branch
-based on `libc-0.2` and running `git cherry-pick -xe commit-sha-on-main` (`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:
+based on `libc-0.2` and running `git cherry-pick -xe commit-sha-on-main`
+(`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 ...
@@ -37,22 +38,23 @@ backport note so the original PR gets crosslinked:
 
 Once the cherry-pick is complete, open a PR targeting `libc-0.2`.
 
-See the [tracking issue](https://github.com/rust-lang/libc/issues/3248) for details.
+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!
 
 The internal structure of this crate is designed to minimize the number of
-`#[cfg]` attributes in order to easily be able to add new items which apply
-to all platforms in the future. As a result, the crate is organized
-hierarchically based on platform. Each module has a number of `#[cfg]`'d
-children, but only one is ever actually compiled. Each module then reexports all
-the contents of its children.
-
-This means that for each platform that libc supports, the path from a
-leaf module to the root will contain all bindings for the platform in question.
+`#[cfg]` attributes in order to easily be able to add new items which apply to
+all platforms in the future. As a result, the crate is organized hierarchically
+based on platform. Each module has a number of `#[cfg]`'d children, but only one
+is ever actually compiled. Each module then reexports all the contents of its
+children.
+
+This means that for each platform that libc supports, the path from a leaf
+module to the root will contain all bindings for the platform in question.
 Consequently, this indicates where an API should be added! Adding an API at a
 particular level in the hierarchy means that it is supported on all the child
 platforms of that level. For example, when adding a Unix API it should be added
@@ -84,7 +86,8 @@ standard, it's just a list shared among all OSs that declare `#[cfg(unix)]`.
 
 ## Test before you commit
 
-We have two automated tests running on [GitHub Actions](https://github.com/rust-lang/libc/actions):
+We have two automated tests running on
+[GitHub Actions](https://github.com/rust-lang/libc/actions):
 
 1. [`libc-test`](https://github.com/gnzlbg/ctest)
   - `cd libc-test && cargo test`
@@ -94,36 +97,30 @@ We have two automated tests running on [GitHub Actions](https://github.com/rust-
 
 ## Breaking change policy
 
-Sometimes an upstream adds a breaking change to their API e.g. removing outdated items,
-changing the type signature, etc. And we probably should follow that change to build the
-`libc` crate successfully. It's annoying to do the equivalent of semver-major versioning
-for each such change. Instead, we mark the item as deprecated and do the actual change
-after a certain period. The steps are:
+Sometimes an upstream adds a breaking change to their API e.g. removing outdated
+items, changing the type signature, etc. And we probably should follow that
+change to build the `libc` crate successfully. It's annoying to do the
+equivalent of semver-major versioning for each such change. Instead, we mark the
+item as deprecated and do the actual change after a certain period. The steps
+are:
 
 1. Add `#[deprecated(since = "", note="")]` attribute to the item.
-  - The `since` field should have a next version of `libc`
-    (e.g., if the current version is `0.2.1`, it should be `0.2.2`).
-  - The `note` field should have a reason to deprecate and a tracking issue to call for comments
-    (e.g., "We consider removing this as the upstream removed it.
-    If you're using it, please comment on #XXX").
+  - The `since` field should have a next version of `libc` (e.g., if the current
+    version is `0.2.1`, it should be `0.2.2`).
+  - The `note` field should have a reason to deprecate and a tracking issue to
+    call for comments (e.g., "We consider removing this as the upstream removed
+    it. If you're using it, please comment on #XXX").
 2. If we don't see any concerns for a while, do the change actually.
 
 ## Supported target policy
 
-When Rust removes a support for a target, the libc crate also may remove the support anytime.
+When Rust removes a support for a target, the libc crate also may remove the
+support at any time.
 
 ## Releasing your change to crates.io
 
-Now that you've done the amazing job of landing your new API or your new
-platform in this crate, the next step is to get that sweet, sweet usage from
-crates.io! The only next step is to bump the version of libc and then publish
-it. If you'd like to get a release out ASAP you can follow these steps:
+This repository uses [release-plz] to handle releases. Once your pull request
+has been merged, a maintainer just needs to verify the generated changelog, then
+merge the bot's release PR. This will automatically publish to crates.io!
 
-1. Increment the patch version number in `Cargo.toml` and `libc-test/Cargo.toml`.
-1. Send a PR to this repository. It should [look like this][example-pr], but it'd
-   also be nice to fill out the description with a small rationale for the
-   release (any rationale is ok though!).
-1. Once merged, the release will be tagged and published by one of the libc crate
-   maintainers.
-
-[example-pr]: https://github.com/rust-lang/libc/pull/2120
+[release-plz]: https://github.com/MarcoIeni/release-plz

README.md

@@ -55,9 +55,14 @@ libc = "0.2"
 
 ## Rust version support
 
-The minimum supported Rust toolchain version is currently **Rust 1.63.0** (libc
-does not currently have any policy regarding changes to the minimum supported
-Rust version; such policy is a work in progress).
+The minimum supported Rust toolchain version is currently **Rust 1.63**.
+
+Increases to the MSRV are allowed to change without a major (i.e. semver-
+breaking) release in order to avoid a ripple effect in the ecosystem. A policy
+for when this may change is a work in progress.
+
+`libc` may continue to compile with Rust versions older than the current MSRV
+but this is not guaranteed.
 
 ## Platform support