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## v0.2 changes
77
8- If you want to add your changes to v0.2, please submit them to the ` libc-0.2 ` branch.
9- If you want to add any breaking changes, it should be submitted to the main branch,
10- which has changes for v0.3.
11- We will support and make a new release for v0.2 until we make the first release of v0.3.
8+ If you want to add your changes to v0.2, please submit them to the ` libc-0.2 `
9+ branch. If you want to add any breaking changes, it should be submitted to the
10+ main branch, which has changes for v0.3. We will support and make a new release
11+ for v0.2 until we make the first release of v0.3.
1212
1313## Adding an API
1414
1515Want to use an API which currently isn't bound in ` libc ` ? It's quite easy to add
1616one!
1717
1818The internal structure of this crate is designed to minimize the number of
19- ` #[cfg] ` attributes in order to easily be able to add new items which apply
20- to all platforms in the future. As a result, the crate is organized
21- hierarchically based on platform. Each module has a number of ` #[cfg] ` 'd
22- children, but only one is ever actually compiled. Each module then reexports all
23- the contents of its children.
24-
25- This means that for each platform that libc supports, the path from a
26- leaf module to the root will contain all bindings for the platform in question.
19+ ` #[cfg] ` attributes in order to easily be able to add new items which apply to
20+ all platforms in the future. As a result, the crate is organized hierarchically
21+ based on platform. Each module has a number of ` #[cfg] ` 'd children, but only one
22+ is ever actually compiled. Each module then reexports all the contents of its
23+ children.
24+
25+ This means that for each platform that libc supports, the path from a leaf
26+ module to the root will contain all bindings for the platform in question.
2727Consequently, this indicates where an API should be added! Adding an API at a
2828particular level in the hierarchy means that it is supported on all the child
2929platforms of that level. For example, when adding a Unix API it should be added
@@ -55,7 +55,8 @@ standard, it's just a list shared between all OSs that declare `#[cfg(unix)]`.
5555
5656## Test before you commit
5757
58- We have two automated tests running on [ GitHub Actions] ( https://github.com/rust-lang/libc/actions ) :
58+ We have two automated tests running on
59+ [ GitHub Actions] ( https://github.com/rust-lang/libc/actions ) :
5960
60611 . [ ` libc-test ` ] ( https://github.com/gnzlbg/ctest )
6162 - ` cd libc-test && cargo test `
@@ -65,36 +66,31 @@ We have two automated tests running on [GitHub Actions](https://github.com/rust-
6566
6667## Breaking change policy
6768
68- Sometimes an upstream adds a breaking change to their API e.g. removing outdated items,
69- changing the type signature, etc. And we probably should follow that change to build the
70- ` libc ` crate successfully. It's annoying to do the equivalent of semver-major versioning
71- for each such change. Instead, we mark the item as deprecated and do the actual change
72- after a certain period. The steps are:
69+ Sometimes an upstream adds a breaking change to their API e.g. removing outdated
70+ items, changing the type signature, etc. And we probably should follow that
71+ change to build the ` libc ` crate successfully. It's annoying to do the
72+ equivalent of semver-major versioning for each such change. Instead, we mark the
73+ item as deprecated and do the actual change after a certain period. The steps
74+ are:
7375
74761 . Add ` #[deprecated(since = "", note="")] ` attribute to the item.
75- - The ` since ` field should have a next version of ` libc `
76- (e.g., if the current version is ` 0.2.1 ` , it should be ` 0.2.2 ` ).
77- - The ` note ` field should have a reason to deprecate and a tracking issue to call for comments
78- (e.g., "We consider removing this as the upstream removed it.
79- If you're using it, please comment on #XXX").
77+ - The ` since ` field should have a next version of ` libc ` (e.g., if the current
78+ version is ` 0.2.1 ` , it should be ` 0.2.2 ` ).
79+ - The ` note ` field should have a reason to deprecate and a tracking issue to
80+ call for comments (e.g., "We consider removing this as the upstream removed
81+ it. If you're using it, please comment on #XXX").
82+
80832 . If we don't see any concerns for a while, do the change actually.
8184
8285## Supported target policy
8386
84- When Rust removes a support for a target, the libc crate also may remove the support anytime.
87+ When Rust removes a support for a target, the libc crate also may remove the
88+ support anytime.
8589
8690## Releasing your change to crates.io
8791
88- Now that you've done the amazing job of landing your new API or your new
89- platform in this crate, the next step is to get that sweet, sweet usage from
90- crates.io! The only next step is to bump the version of libc and then publish
91- it. If you'd like to get a release out ASAP you can follow these steps:
92-
93- 1 . Increment the patch version number in ` Cargo.toml ` and ` libc-test/Cargo.toml ` .
94- 1 . Send a PR to this repository. It should [ look like this] [ example-pr ] , but it'd
95- also be nice to fill out the description with a small rationale for the
96- release (any rationale is ok though!).
97- 1 . Once merged, the release will be tagged and published by one of the libc crate
98- maintainers.
92+ This repository uses [ release-plz] to handle releases. Once your pull request
93+ has been merged, a maintainer just needs to verify the generated changelog, then
94+ merge the bot's release PR. This will automatically publish to crates.io!
9995
100- [ example-pr ] : https://github.com/rust-lang/libc/pull/2120
96+ [ release-plz ] : https://github.com/MarcoIeni/release-plz
0 commit comments