actions
/
mdBook
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Wrap lines and add more whitespace in CONTRIBUTING.md

This commit is contained in:
Mathieu David 2017-05-17 18:36:52 +02:00
parent 1442923a0a
commit 0f67cae1ef
1 changed files with 28 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
CONTRIBUTING.md
View File

@ -4,15 +4,26 @@ Welcome stranger!
If you have come here to learn how to contribute to mdBook, we have some tips for you! If you have come here to learn how to contribute to mdBook, we have some tips for you!
First of all, don't hesitate to ask questions! Use the [issue tracker](https://github.com/azerupi/mdBook/issues), no question is too simple. If we don't respond in a couple of days, ping us @azerupi, @steveklabnik, @frewsxcv it might just be that we forgot. :wink: First of all, don't hesitate to ask questions!
Use the [issue tracker](https://github.com/azerupi/mdBook/issues), no question is too simple.
If we don't respond in a couple of days, ping us @azerupi, @steveklabnik, @frewsxcv it might just be that we forgot. :wink:
### Issues to work on ### Issues to work on
Any issue is up for the grabbing, but if you are starting out, you might be interested in the [E-Easy issues](https://github.com/azerupi/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AE-Easy). Those are issues that are considered more straightforward for beginners to Rust or the codebase itself. These issues can be a good launching pad for more involved issues. Easy tasks for a first time contribution include documentation improvements, new tests, examples, updating dependencies, etc. Any issue is up for the grabbing, but if you are starting out, you might be interested in the
[E-Easy issues](https://github.com/azerupi/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AE-Easy).
Those are issues that are considered more straightforward for beginners to Rust or the codebase itself.
These issues can be a good launching pad for more involved issues. Easy tasks for a first time contribution
include documentation improvements, new tests, examples, updating dependencies, etc.
If you come from a web development background, you might be interested in issues related to web technologies tagged [A-JavaScript](https://github.com/azerupi/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AA-JavaScript), [A-Style](https://github.com/azerupi/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AA-Style), [A-HTML](https://github.com/azerupi/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AA-HTML) or [A-Mobile](https://github.com/azerupi/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AA-Mobile). If you come from a web development background, you might be interested in issues related to web technologies tagged
[A-JavaScript](https://github.com/azerupi/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AA-JavaScript),
[A-Style](https://github.com/azerupi/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AA-Style),
[A-HTML](https://github.com/azerupi/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AA-HTML) or
[A-Mobile](https://github.com/azerupi/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AA-Mobile).
When you decide you want to work on a specific issue, ping us on that issue so that we can assign it to you. Again, do not hesitate to ask questions. We will gladly mentor anyone that want to tackle an issue. When you decide you want to work on a specific issue, ping us on that issue so that we can assign it to you.
Again, do not hesitate to ask questions. We will gladly mentor anyone that want to tackle an issue.
Issues on the issue tracker are categorized with the following labels: Issues on the issue tracker are categorized with the following labels:
@ -23,10 +34,12 @@ Issues on the issue tracker are categorized with the following labels:
- **T**-prefixed labels show the type of issue - **T**-prefixed labels show the type of issue
### Building mdBook ### Building mdBook
mdBook builds on stable Rust, if you want to build mdBook from source, here are the steps to follow: mdBook builds on stable Rust, if you want to build mdBook from source, here are the steps to follow:
1. Navigate to the directory of your choice 1. Navigate to the directory of your choice
0. Clone this repository with git. 0. Clone this repository with git.
``` ```
git clone https://github.com/azerupi/mdBook.git git clone https://github.com/azerupi/mdBook.git
``` ```
@ -37,11 +50,15 @@ The resulting binary can be found in `mdBook/target/debug/` under the name `mdBo
### Making changes to the style ### Making changes to the style
mdBook doesn't use CSS directly but uses [Stylus](http://stylus-lang.com/), a CSS-preprocessor which compiles to CSS. mdBook doesn't use CSS directly but uses [Stylus](http://stylus-lang.com/), a CSS-preprocessor which compiles to CSS.
When you want to change the style, it is important to not change the CSS directly because any manual modification to the CSS files will be overwritten when compiling the stylus files. Instead, you should make your changes directly in the [stylus files](https://github.com/azerupi/mdBook/tree/master/src/theme/stylus) and regenerate the CSS. When you want to change the style, it is important to not change the CSS directly because any manual modification to
the CSS files will be overwritten when compiling the stylus files. Instead, you should make your changes directly in the
[stylus files](https://github.com/azerupi/mdBook/tree/master/src/theme/stylus) and regenerate the CSS.
For this to work, you first need [Node and NPM](https://nodejs.org/en/) installed on your machine. Then run the following inside of the mdBook directory: For this to work, you first need [Node and NPM](https://nodejs.org/en/) installed on your machine.
Then run the following inside of the mdBook directory:
``` ```
npm install npm install
@ -57,8 +74,11 @@ This should automatically call the appropriate stylus command to recompile the f
### Making a pull-request ### Making a pull-request
When you feel comfortable that your changes could be integrated into mdBook, you can create a pull-request on GitHub. One of the core maintainers will then approve the changes or request some changes before it gets merged. When you feel comfortable that your changes could be integrated into mdBook, you can create a pull-request on GitHub.
One of the core maintainers will then approve the changes or request some changes before it gets merged.
If you want to make your pull-request even better, you might want to run [Clippy](https://github.com/Manishearth/rust-clippy) and [rustfmt](https://github.com/rust-lang-nursery/rustfmt) on the code first. This is not a requirement though and will never block a pull-request from being merged. If you want to make your pull-request even better, you might want to run [Clippy](https://github.com/Manishearth/rust-clippy)
and [rustfmt](https://github.com/rust-lang-nursery/rustfmt) on the code first.
This is not a requirement though and will never block a pull-request from being merged.
That's it, happy contributions! :tada: :tada: :tada: That's it, happy contributions! :tada: :tada: :tada: