You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+43-18Lines changed: 43 additions & 18 deletions
Original file line number
Diff line number
Diff line change
@@ -7,30 +7,39 @@ If you have come here to learn how to contribute to mdBook, we have some tips fo
7
7
First of all, don't hesitate to ask questions!
8
8
Use the [issue tracker](https://github.com/rust-lang/mdBook/issues), no question is too simple.
9
9
10
+
### Issue assignment
11
+
12
+
**:warning: Important :warning:**
13
+
14
+
Before working on pull request, please ping us on the corresponding issue.
15
+
The current PR backlog is beyond what we can process at this time.
16
+
Only issues that have an [`E-Help-wanted`](https://github.com/rust-lang/mdBook/labels/E-Help-wanted) or [`Feature accepted`](https://github.com/rust-lang/mdBook/labels/Feature%20accepted) label will likely receive reviews.
17
+
If there isn't already an open issue for what you want to work on, please open one first to see if it is something we would be available to review.
18
+
10
19
### Issues to work on
11
20
12
-
Any issue is up for the grabbing, but if you are starting out, you might be interested in the
21
+
If you are starting out, you might be interested in the
When you decide you want to work on a specific issue, ping us on that issue so that we can assign it to you.
33
+
When you decide you want to work on a specific issue, and it isn't already assigned to someone else, assign the issue to yourself by leaving a comment with the text `@rustbot claim`.
25
34
Again, do not hesitate to ask questions. We will gladly mentor anyone that want to tackle an issue.
26
35
27
36
Issues on the issue tracker are categorized with the following labels:
28
37
29
38
-**A**-prefixed labels state which area of the project an issue relates to.
30
39
-**E**-prefixed labels show an estimate of the experience necessary to fix the issue.
31
-
-**M**-prefixed labels are meta-issues used for questions, discussions, or tracking issues
40
+
-**M**-prefixed labels are meta-issues regarding the management of the mdBook project itself
32
41
-**S**-prefixed labels show the status of the issue
33
-
-**T**-prefixed labels show the type of issue
42
+
-**C**-prefixed labels show the category of issue
34
43
35
44
### Building mdBook
36
45
@@ -59,7 +68,7 @@ This will ensure we have good quality source code that is better for us all to m
59
68
[rustfmt](https://github.com/rust-lang/rustfmt) has a lot more information on the project.
60
69
The quick guide is
61
70
62
-
1. Install it
71
+
1. Install it (`rustfmt` is usually installed by default via [rustup](https://rustup.rs/)):
63
72
```
64
73
rustup component add rustfmt
65
74
```
@@ -71,18 +80,15 @@ The quick guide is
71
80
```
72
81
cargo fmt
73
82
```
74
-
When run through `cargo` it will format all bin and lib files in the current crate.
83
+
When run through `cargo` it will format all bin and lib files in the current package.
75
84
76
85
For more information, such as running it from your favourite editor, please see the `rustfmt` project. [rustfmt](https://github.com/rust-lang/rustfmt)
77
86
78
87
79
88
#### Finding Issues with Clippy
80
89
81
-
Clippy is a code analyser/linter detecting mistakes, and therefore helps to improve your code.
82
-
Like formatting your code with `rustfmt`, running clippy regularly and before your Pull Request will
83
-
help us maintain awesome code.
84
-
85
-
The best documentation can be found over at [rust-clippy](https://github.com/rust-lang/rust-clippy)
90
+
[Clippy](https://doc.rust-lang.org/clippy/) is a code analyser/linter detecting mistakes, and therefore helps to improve your code.
91
+
Like formatting your code with `rustfmt`, running clippy regularly and before your Pull Request will help us maintain awesome code.
86
92
87
93
1. To install
88
94
```
@@ -93,17 +99,36 @@ The best documentation can be found over at [rust-clippy](https://github.com/rus
93
99
cargo clippy
94
100
```
95
101
96
-
Clippy has an ever growing list of checks, that are managed in [lint files](https://rust-lang.github.io/rust-clippy/master/index.html).
102
+
### Change requirements
103
+
104
+
Please consider the following when making a change:
105
+
106
+
* Almost all changes that modify the Rust code must be accompanied with a test.
107
+
108
+
* Almost all features and changes must update the documentation.
109
+
mdBook has the [mdBook Guide](https://rust-lang.github.io/mdBook/) whose source is at <https://github.com/rust-lang/mdBook/tree/master/guide>.
110
+
111
+
* Almost all Rust items should be documented with doc comments.
112
+
See the [Rustdoc Book](https://doc.rust-lang.org/rustdoc/) for more information on writing doc comments.
113
+
114
+
* Breaking the API can only be done in major SemVer releases.
115
+
These are done very infrequently, so it is preferred to avoid these when possible.
116
+
See [SemVer Compatibility](https://doc.rust-lang.org/cargo/reference/semver.html) for more information on what a SemVer breaking change is.
117
+
118
+
(Note: At this time, some SemVer breaking changes are inevitable due to the current code structure.
119
+
An example is adding new fields to the config structures.
120
+
These are intended to be fixed in the next major release.)
121
+
122
+
* Similarly, the CLI interface is considered to be stable.
123
+
Care should be taken to avoid breaking existing workflows.
124
+
125
+
* Check out the [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/) for guidelines on designing the API.
97
126
98
127
### Making a pull-request
99
128
100
129
When you feel comfortable that your changes could be integrated into mdBook, you can create a pull-request on GitHub.
101
130
One of the core maintainers will then approve the changes or request some changes before it gets merged.
102
131
103
-
If you want to make your pull-request even better, you might want to run [Clippy](https://github.com/Manishearth/rust-clippy)
104
-
and [rustfmt](https://github.com/rust-lang/rustfmt) on the code first.
105
-
This is not a requirement though and will never block a pull-request from being merged.
0 commit comments