From 4c96f6c71f301fd836551803482eee936fc19025 Mon Sep 17 00:00:00 2001 From: Sergio Benitez Date: Thu, 29 Sep 2016 18:56:11 -0700 Subject: [PATCH] Revamp README: add documentation, testing, and contributing sections. --- README.md | 108 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 62 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 30d211cf..f3e42e0b 100644 --- a/README.md +++ b/README.md @@ -26,70 +26,86 @@ route resulting in the string `Hello, 58 year old named John!` being sent to the browser. If an `` string was passed in that can't be parsed as a `u8`, the route won't get called, resulting in a 404 error. -## Overview +## Documentation -Rocket employs code generation to remove the need for boilerplate involved with -parsing requests and request parameters, prevent invalid and/or incorrect -requests from invoking a user's request handler, and allow the user to define -what is valid and/or correct. +Rocket is extensively documented: -Rocket uses type _guards_, or _constraints_, on request handlers to -accomplishing it's safety and correctness goals. In Rocket, handlers are _only_ -invoked if all types that appear in the request handler's argument list can be -derived from the incoming request. - -In their simplest incarnation, guards can be types expected of parameters in a -matched path. This is illustrated in the previous example where the `hello` -request handler is only be invoked if the dynamic path parameter `` parses -as a `u8`. Guards can also be derived directly from a request. For instance, you -can define an `AdminUser` type that can be derived only if the proper cookies -were sent along with the request. Then, by simply including the type in a -handler's argument list as follows: - - #[get("/admin/post/")] - fn admin(user: AdminUser, id: isize) -> { .. } - -you can be assured that the handler will be invoked _only_ if an administrative -user is logged in. Any number of such guards can be included. For example, to -retrieve the request's cookies along with the admin user, simply include the -`&Cookies` type in the argument list: - - #[get("/admin/post/")] - fn admin(user: AdminUser, cookies: &Cookies, id: isize) -> { .. } - -Full documentation about built-in request guards is coming soon. + * [Quickstart](guide/quickstart): How to get started as quickly as possible. + * [Getting Started](guide/getting_started): How to start your first project. + * [Overview](overview): A brief introduction. + * [Guide](guide): A detailed guide and reference to every component. + * [API Documentation](api): The "rustdocs" (API documentation). ## Building ### Nightly Rocket requires a nightly version of Rust as it makes heavy use of syntax -extensions. This also means that the first two unwieldly lines in the Rust file -above are required. +extensions. This means that the first two unwieldly lines in the introductory +example above are required. + +### Core, Codegen, and Contrib + +All of the Rocket libraries are managed by Cargo. As a result, compiling them is +simple. + + * Core: `cd lib && cargo build` + * Codegen: `cd codegen && cargo build` + * Contrib: `cd contrib && cargo build` ### Examples -Try running the examples in the `examples/` folder. For instance, the following -sequence of commands builds and runs the `Hello, world!` example: +Rocket ships with an extensive number of examples in the `examples/` directory +which can be compiled and run with Cargo. For instance, the following sequence +of commands builds and runs the `Hello, world!` example: ``` cd examples/hello_world cargo run ``` -Then visit `localhost:8000`. You should see `Hello, world!`. +You should see `Hello, world!` by visiting `http://localhost:8000`. -### OS X +## Testing -Apple has stopped shipping `openssl` with OS X.11. As such, if your build fails -to compile with some `openssl` related errors, you'll need to install `openssl`, -`cargo clean`, and then `cargo build` again. Here are some lightweight -instructions: +To test Rocket, simply run `./scripts/test.sh` from the root of the source tree. +This will build and test the `core`, `codegen`, and `contrib` libraries as well +as all of the examples. This is the script that gets run by Travis CI. -``` -brew install openssl -brew link --force openssl -export OPENSSL_INCLUDE_DIR=`brew --prefix openssl`/include -export OPENSSL_LIB_DIR=`brew --prefix openssl`/lib -``` +### Core +Testing for the core library is done inline in the corresponding module. For +example, the tests for routing can be found at the bottom of the +`lib/src/router/mod.rs` file. + +### Codegen + +Code generation tests can be found in `codegen/tests`. We use the +[compiletest](https://crates.io/crates/compiletest_rs) library, which was +extracted from `rustc`, for testing. See the [compiler test +documentation](https://github.com/rust-lang/rust/blob/master/COMPILER_TESTS.md) +for information on how to write compiler tests. + +## Contributing + +Contributions are absolutely, positively welcome and encouraged! Contributions +come in many forms. You could: + + 1. Submit a feature request or bug report as an [issue](https://github.com/SergioBenitez/Rocket/issues). + 2. Comment on [issues that require + feedback](https://github.com/SergioBenitez/Rocket/issues?q=is%3Aissue+is%3Aopen+label%3A%22feedback+wanted%22). + 3. Contribute code via [pull requests](https://github.com/SergioBenitez/Rocket/pulls). + +We aim to keep Rocket's code quality at the highest level. This means that any +code you contribute must be: + + * **Commented:** Public items _must_ be commented. + * **Documented:** Exposed items _must_ have rustdoc comments with + examples, if applicable. + * **Styled:** Your code should be `rustfmt`'d when possible. + * **Simple:** Your code should accomplish its task as simply and + idiomatically as possible. + * **Tested:** You must add (and pass) convincing tests for any functionality you add. + * **Focused:** Your code should do what it's supposed to do and nothing more. + +All pull requests are code reviewed and tested by the CI.