1
1
# Contributing to ` libc `
2
2
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.
5
5
6
6
## v1.0 Roadmap
7
7
@@ -19,14 +19,15 @@ Good candidates will usually meet the following:
19
19
additions should always have a usecase, hopefully).
20
20
21
21
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.
24
24
25
25
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:
30
31
31
32
```
32
33
# ... original commit message ...
@@ -37,22 +38,23 @@ backport note so the original PR gets crosslinked:
37
38
38
39
Once the cherry-pick is complete, open a PR targeting ` libc-0.2 ` .
39
40
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.
41
43
42
44
## Adding an API
43
45
44
46
Want to use an API which currently isn't bound in ` libc ` ? It's quite easy to add
45
47
one!
46
48
47
49
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.
56
58
Consequently, this indicates where an API should be added! Adding an API at a
57
59
particular level in the hierarchy means that it is supported on all the child
58
60
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)]`.
84
86
85
87
## Test before you commit
86
88
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 ) :
88
91
89
92
1 . [ ` libc-test ` ] ( https://github.com/gnzlbg/ctest )
90
93
- ` cd libc-test && cargo test `
@@ -94,36 +97,30 @@ We have two automated tests running on [GitHub Actions](https://github.com/rust-
94
97
95
98
## Breaking change policy
96
99
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:
102
106
103
107
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").
109
113
2 . If we don't see any concerns for a while, do the change actually.
110
114
111
115
## Supported target policy
112
116
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.
114
119
115
120
## Releasing your change to crates.io
116
121
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!
121
125
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
0 commit comments