From 7a59591109dbd6fa4c26df13cd23140df2a66622 Mon Sep 17 00:00:00 2001 From: Mathieu David Date: Tue, 16 May 2017 22:02:07 +0200 Subject: [PATCH 1/4] Added a contributing file --- CONTRIBUTING.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..a7e0c2a0 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,64 @@ +# Contributing + +Welcome stranger! + +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: + +### 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. Simple documentation improvements are also very highly appreciated! + +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. + +Issues on the issue tracker are categorized with the following labels: + +- **A**-prefixed labels state which area of the project an issue relates to. +- **E**-prefixed labels show an estimate of the experience necessary to fix the issue. +- **M**-prefixed labels are meta-issues used for questions, discussions, or tracking issues +- **S**-prefixed labels show the status of the issue +- **T**-prefixed labels show the type of issue + +### Building mdBook +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 +0. Clone this repository with git. + ``` + git clone https://github.com/azerupi/mdBook.git + ``` +0. Navigate into the newly created `mdBook` directory +0. Run `cargo build` + +The resulting binary can be found in `mdBook/target/debug/` under the name `mdBook` or `mdBook.exe`. + + +### 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. + +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: + +``` +npm install +``` + +When that finished, you can simply regenerate the CSS files by building mdBook with the following command: + +``` +cargo build --features=regenerate-css +``` + +This should automatically call the appropriate stylus command to recompile the files to CSS and include them in the project. + +### 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. + +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: From 9447274fa5a92cfe5d102a4df4d432e0e1b2a80c Mon Sep 17 00:00:00 2001 From: Mathieu David Date: Tue, 16 May 2017 22:10:24 +0200 Subject: [PATCH 2/4] Modify the Readme for the new contribution guide --- README.md | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 55e18f48..679e4c66 100644 --- a/README.md +++ b/README.md @@ -23,9 +23,6 @@ mdBook is a utility to create modern online books from Markdown files. -**This project is still evolving.** -See [#90](https://github.com/azerupi/mdBook/issues/90) - ## What does it look like? @@ -114,13 +111,11 @@ See the [Documentation](http://azerupi.github.io/mdBook/lib/lib.html) and the [A Contributions are highly appreciated and encouraged! Don't hesitate to participate to discussions in the issues, propose new features and ask for help. -If you are not very confident with Rust, **I will be glad to mentor as best as I can if you decide to tackle an issue or new feature.** +If you are just starting out with Rust, there are a series of issus that are tagged [E-Easy](https://github.com/azerupi/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AE-Easy) and **we will gladly mentor you** so that you can successfully go through the process of fixing a bug or adding a new feature! Let us know if you need any help. -People who are not familiar with the code can look at [issues that are tagged **easy**](https://github.com/azerupi/mdBook/labels/Easy). A lot of issues are also related to web development, so people that are not comfortable with Rust can also participate! :wink: - -You can pick any issue you want to work on. Usually it's a good idea to ask if someone is already working on it and if not to claim the issue. +For more info about contributing, check out our [contribution guide](CONTRIBUTING.md) who helps you go through the build and contribution process! ## License -All the code is released under the ***Mozilla Public License v2.0***, for more information take a look at the [LICENSE](LICENSE) file. +All the code in this repository is released under the ***Mozilla Public License v2.0***, for more information take a look at the [LICENSE](LICENSE) file. From 1442923a0a1646c4c7f46279c3cd56f489144582 Mon Sep 17 00:00:00 2001 From: Mathieu David Date: Tue, 16 May 2017 22:16:59 +0200 Subject: [PATCH 3/4] Add simple issue examples --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a7e0c2a0..c13d6136 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,7 +8,7 @@ First of all, don't hesitate to ask questions! Use the [issue tracker](https://g ### 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. Simple documentation improvements are also very highly appreciated! +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). From 0f67cae1efb747aab19647152077d6217f680673 Mon Sep 17 00:00:00 2001 From: Mathieu David Date: Wed, 17 May 2017 18:36:52 +0200 Subject: [PATCH 4/4] Wrap lines and add more whitespace in CONTRIBUTING.md --- CONTRIBUTING.md | 36 ++++++++++++++++++++++++++++-------- 1 file changed, 28 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c13d6136..015ff53d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,15 +4,26 @@ Welcome stranger! 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 -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: @@ -23,10 +34,12 @@ Issues on the issue tracker are categorized with the following labels: - **T**-prefixed labels show the type of issue ### Building mdBook + 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 0. Clone this repository with 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 + 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 @@ -57,8 +74,11 @@ This should automatically call the appropriate stylus command to recompile the f ### 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: