From 698f8c2f01ea549d77d7dc3338a12e04c11057b9 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Wed, 17 Apr 2024 14:02:58 +0200 Subject: Adding upstream version 1.64.0+dfsg1. Signed-off-by: Daniel Baumann --- vendor/mdbook/CONTRIBUTING.md | 130 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 vendor/mdbook/CONTRIBUTING.md (limited to 'vendor/mdbook/CONTRIBUTING.md') diff --git a/vendor/mdbook/CONTRIBUTING.md b/vendor/mdbook/CONTRIBUTING.md new file mode 100644 index 000000000..72010ad2e --- /dev/null +++ b/vendor/mdbook/CONTRIBUTING.md @@ -0,0 +1,130 @@ +# 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/rust-lang/mdBook/issues), no question is too simple. + +### 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/rust-lang/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/rust-lang/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AA-JavaScript), +[A-Style](https://github.com/rust-lang/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AA-Style), +[A-HTML](https://github.com/rust-lang/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AA-HTML) or +[A-Mobile](https://github.com/rust-lang/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/rust-lang/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`. + +### Code Quality + +We love code quality and Rust has some excellent tools to assist you with contributions. + +#### Formatting Code with rustfmt + +Before you make your Pull Request to the project, please run it through the `rustfmt` utility. +This will ensure we have good quality source code that is better for us all to maintain. + +[rustfmt](https://github.com/rust-lang/rustfmt) has a lot more information on the project. +The quick guide is + +1. Install it + ``` + rustup component add rustfmt + ``` +1. You can now run `rustfmt` on a single file simply by... + ``` + rustfmt src/path/to/your/file.rs + ``` + ... or you can format the entire project with + ``` + cargo fmt + ``` + When run through `cargo` it will format all bin and lib files in the current crate. + +For more information, such as running it from your favourite editor, please see the `rustfmt` project. [rustfmt](https://github.com/rust-lang/rustfmt) + + +#### Finding Issues with Clippy + +Clippy is a code analyser/linter detecting mistakes, and therefore helps to improve your code. +Like formatting your code with `rustfmt`, running clippy regularly and before your Pull Request will +help us maintain awesome code. + +The best documentation can be found over at [rust-clippy](https://github.com/rust-lang/rust-clippy) + +1. To install + ``` + rustup component add clippy + ``` +2. Running clippy + ``` + cargo clippy + ``` + +Clippy has an ever growing list of checks, that are managed in [lint files](https://rust-lang.github.io/rust-clippy/master/index.html). + +### 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/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: + +## Browser compatibility and testing + +Currently we don't have a strict browser compatibility matrix due to our limited resources. +We generally strive to keep mdBook compatible with a relatively recent browser on all of the most major platforms. +That is, supporting Chrome, Safari, Firefox, Edge on Windows, macOS, Linux, iOS, and Android. +If possible, do your best to avoid breaking older browser releases. + +Any change to the HTML or styling is encouraged to manually check on as many browsers and platforms that you can. +Unfortunately at this time we don't have any automated UI or browser testing, so your assistance in testing is appreciated. + +## Updating higlight.js + +The following are instructions for updating [highlight.js](https://highlightjs.org/). + +1. Clone the repository at +1. Check out a tagged release (like `10.1.1`). +1. Run `npm install` +1. Run `node tools/build.js :common apache armasm coffeescript d handlebars haskell http julia nginx properties r scala x86asm yaml` +1. Compare the language list that it spits out to the one in [`syntax-highlighting.md`](https://github.com/camelid/mdBook/blob/master/guide/src/format/theme/syntax-highlighting.md). If any are missing, add them to the list and rebuild (and update these docs). If any are added to the common set, add them to `syntax-highlighting.md`. +1. Copy `build/highlight.min.js` to mdbook's directory [`highlight.js`](https://github.com/rust-lang/mdBook/blob/master/src/theme/highlight.js). +1. Be sure to check the highlight.js [CHANGES](https://github.com/highlightjs/highlight.js/blob/main/CHANGES.md) for any breaking changes. Breaking changes that would affect users will need to wait until the next major release. +1. Build mdbook with the new file and build some books with the new version and compare the output with a variety of languages to see if anything changes. The [test_book](https://github.com/rust-lang/mdBook/tree/master/test_book) contains a chapter with many languages to examine. -- cgit v1.2.3