Skip to content

Commit f508b33

Browse files
authored
Merge pull request #4071 from tgross35/docs-sync
Sync docs from 0.2 to main
2 parents eccfe7a + 8abab57 commit f508b33

File tree

2 files changed

+46
-44
lines changed

2 files changed

+46
-44
lines changed

CONTRIBUTING.md

Lines changed: 38 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Contributing to `libc`
22

3-
Welcome! If you are reading this document, it means you are interested in contributing
4-
to the `libc` crate.
3+
Welcome! If you are reading this document, it means you are interested in
4+
contributing to the `libc` crate.
55

66
## v1.0 Roadmap
77

@@ -19,14 +19,15 @@ Good candidates will usually meet the following:
1919
additions should always have a usecase, hopefully).
2020

2121
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
23-
picks in a batch.
22+
picked to the `libc-0.2` branch. A maintainer will likely do these cherry picks
23+
in a batch.
2424

2525
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` (`git
27-
cherry-pick -xe start-sha^..end-sha` if a range of commits is needed). `git`
28-
will automatically add the "cherry picked from commit" note, but try to add a
29-
backport note so the original PR gets crosslinked:
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:
3031

3132
```
3233
# ... original commit message ...
@@ -37,22 +38,23 @@ backport note so the original PR gets crosslinked:
3738

3839
Once the cherry-pick is complete, open a PR targeting `libc-0.2`.
3940

40-
See the [tracking issue](https://github.com/rust-lang/libc/issues/3248) for details.
41+
See the [tracking issue](https://github.com/rust-lang/libc/issues/3248) for
42+
details.
4143

4244
## Adding an API
4345

4446
Want to use an API which currently isn't bound in `libc`? It's quite easy to add
4547
one!
4648

4749
The internal structure of this crate is designed to minimize the number of
48-
`#[cfg]` attributes in order to easily be able to add new items which apply
49-
to all platforms in the future. As a result, the crate is organized
50-
hierarchically based on platform. Each module has a number of `#[cfg]`'d
51-
children, but only one is ever actually compiled. Each module then reexports all
52-
the contents of its children.
53-
54-
This means that for each platform that libc supports, the path from a
55-
leaf module to the root will contain all bindings for the platform in question.
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.
5658
Consequently, this indicates where an API should be added! Adding an API at a
5759
particular level in the hierarchy means that it is supported on all the child
5860
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)]`.
8486

8587
## Test before you commit
8688

87-
We have two automated tests running on [GitHub Actions](https://github.com/rust-lang/libc/actions):
89+
We have two automated tests running on
90+
[GitHub Actions](https://github.com/rust-lang/libc/actions):
8891

8992
1. [`libc-test`](https://github.com/gnzlbg/ctest)
9093
- `cd libc-test && cargo test`
@@ -94,36 +97,30 @@ We have two automated tests running on [GitHub Actions](https://github.com/rust-
9497

9598
## Breaking change policy
9699

97-
Sometimes an upstream adds a breaking change to their API e.g. removing outdated items,
98-
changing the type signature, etc. And we probably should follow that change to build the
99-
`libc` crate successfully. It's annoying to do the equivalent of semver-major versioning
100-
for each such change. Instead, we mark the item as deprecated and do the actual change
101-
after a certain period. The steps are:
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:
102106

103107
1. Add `#[deprecated(since = "", note="")]` attribute to the item.
104-
- The `since` field should have a next version of `libc`
105-
(e.g., if the current version is `0.2.1`, it should be `0.2.2`).
106-
- The `note` field should have a reason to deprecate and a tracking issue to call for comments
107-
(e.g., "We consider removing this as the upstream removed it.
108-
If you're using it, please comment on #XXX").
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").
109113
2. If we don't see any concerns for a while, do the change actually.
110114

111115
## Supported target policy
112116

113-
When Rust removes a support for a target, the libc crate also may remove the support anytime.
117+
When Rust removes a support for a target, the libc crate also may remove the
118+
support at any time.
114119

115120
## Releasing your change to crates.io
116121

117-
Now that you've done the amazing job of landing your new API or your new
118-
platform in this crate, the next step is to get that sweet, sweet usage from
119-
crates.io! The only next step is to bump the version of libc and then publish
120-
it. If you'd like to get a release out ASAP you can follow these steps:
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!
121125

122-
1. Increment the patch version number in `Cargo.toml` and `libc-test/Cargo.toml`.
123-
1. Send a PR to this repository. It should [look like this][example-pr], but it'd
124-
also be nice to fill out the description with a small rationale for the
125-
release (any rationale is ok though!).
126-
1. Once merged, the release will be tagged and published by one of the libc crate
127-
maintainers.
128-
129-
[example-pr]: https://github.com/rust-lang/libc/pull/2120
126+
[release-plz]: https://github.com/MarcoIeni/release-plz

README.md

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -55,9 +55,14 @@ libc = "0.2"
5555

5656
## Rust version support
5757

58-
The minimum supported Rust toolchain version is currently **Rust 1.63.0** (libc
59-
does not currently have any policy regarding changes to the minimum supported
60-
Rust version; such policy is a work in progress).
58+
The minimum supported Rust toolchain version is currently **Rust 1.63**.
59+
60+
Increases to the MSRV are allowed to change without a major (i.e. semver-
61+
breaking) release in order to avoid a ripple effect in the ecosystem. A policy
62+
for when this may change is a work in progress.
63+
64+
`libc` may continue to compile with Rust versions older than the current MSRV
65+
but this is not guaranteed.
6166

6267
## Platform support
6368

0 commit comments

Comments
 (0)