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,23 +66,26 @@ 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
@@ -90,11 +94,12 @@ platform in this crate, the next step is to get that sweet, sweet usage from
9094crates.io! The only next step is to bump the version of libc and then publish
9195it. If you'd like to get a release out ASAP you can follow these steps:
9296
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.
97+ 1 . Increment the patch version number in ` Cargo.toml ` and
98+ ` libc-test/Cargo.toml ` .
99+ 1 . Send a PR to this repository. It should [ look like this] [ example-pr ] , but
100+ it would also be nice to fill out the description with a small rationale for
101+ the release (any rationale is ok though!).
102+ 1 . Once merged, the release will be tagged and published by one of the libc
103+ crate maintainers.
99104
100105[ example-pr ] : https://github.com/rust-lang/libc/pull/2120
0 commit comments