Update contribution guidelines

Signed-off-by: Robert Vojta <rvojta@me.com>
This commit is contained in:
Robert Vojta 2019-10-02 09:17:25 +02:00
parent bb42c52f81
commit fe05e548c2
No known key found for this signature in database
GPG Key ID: 082AAEA8854E3D88

View File

@ -2,58 +2,6 @@
I would appreciate any contributions to this crate. However, some things are handy to know. I would appreciate any contributions to this crate. However, some things are handy to know.
## Architecture
Crossterm is using ANSI escape codes by default for both Unix and for Windows systems except
for Windows versions lower than 10. Crossterm uses WinAPI in this case.
### Crates
The `crossterm` crate consists of 7 crates:
* [cursor](https://github.com/crossterm-rs/crossterm-cursor)
* [input](https://github.com/crossterm-rs/crossterm-input)
* [style](https://github.com/crossterm-rs/crossterm-style)
* [terminal](https://github.com/crossterm-rs/crossterm-terminal)
* [screen](https://github.com/crossterm-rs/crossterm-screen)
* [utils](https://github.com/crossterm-rs/crossterm-utils)
* [winapi](https://github.com/crossterm-rs/crossterm-winapi)
### Module structure
If you would like to contribute, then please follow the existing structure. For
example, the cursor crate has the following file structure:
```text
└── src
├── cursor
│   ├── ansi.rs
│   └── windows.rs
├── cursor.rs
├── lib.rs
├── sys
│   ├── unix.rs
│   └── windows.rs
└── sys.rs
```
* `src/lib.rs` - public interface of the crate (for example `TerminalCursor` struct)
* `src/cursor.rs` - `Cursor` trait, which must be implement by all platform specific cursors
* `src/cursor/ansi.rs` - `AnsiCursor` structure implementing the `Cursor` trait
* `src/cursor/windows.rs` - `WinApiCursor` structure implementing the `Cursor` trait
* `src/sys` - platform specific logic
The above structure is followed by other crates.
Why I have chosen this design:
* You can easily add new platform by implementing the trait
* You can keep the functionality for different platforms separated
* You have one API the user can call like in the `src/lib.rs`
Try to avoid changing `src/lib.rs` a lot, because it contains API for
the end-user.
## Code style ## Code style
### Import order ### Import order
@ -67,9 +15,7 @@ All imports are semantically grouped and ordered. The order is:
- current module (`use self::...`) - current module (`use self::...`)
- module declaration (`mod ...`) - module declaration (`mod ...`)
There must be an empty line between groups. There must be an empty line between groups. An example:
An example:
```rust ```rust
use crossterm_utils::{csi, write_cout, Result}; use crossterm_utils::{csi, write_cout, Result};
@ -79,7 +25,7 @@ use crate::sys::{get_cursor_position, show_cursor};
use super::Cursor; use super::Cursor;
``` ```
#### CLion tips #### CLion Tips
The CLion IDE does this for you (_Menu_ -> _Code_ -> _Optimize Imports_). Be aware that the CLion sorts The CLion IDE does this for you (_Menu_ -> _Code_ -> _Optimize Imports_). Be aware that the CLion sorts
imports in a group in a different way when compared to the `rustfmt`. It's effectively two steps operation imports in a group in a different way when compared to the `rustfmt`. It's effectively two steps operation
@ -91,7 +37,7 @@ to get proper grouping & sorting:
Second step can be automated via _CLion_ -> _Preferences_ -> Second step can be automated via _CLion_ -> _Preferences_ ->
_Languages & Frameworks_ -> _Rust_ -> _Rustfmt_ -> _Run rustfmt on save_. _Languages & Frameworks_ -> _Rust_ -> _Rustfmt_ -> _Run rustfmt on save_.
### Max line length ### Max Line Length
| Type | Max line length | | Type | Max line length |
| :--- | ---: | | :--- | ---: |
@ -104,7 +50,6 @@ default value.
120 is because of the GitHub. The editor & viewer width there is +- 123 characters. 120 is because of the GitHub. The editor & viewer width there is +- 123 characters.
###
### Warnings ### Warnings
The code must be warning free. It's quite hard to find an error if the build logs are polluted with warnings. The code must be warning free. It's quite hard to find an error if the build logs are polluted with warnings.
@ -112,7 +57,7 @@ If you decide to silent a warning with (`#[allow(...)]`), please add a comment w
Always consult the [Travis CI](https://travis-ci.org/crossterm-rs/crossterm/pull_requests) build logs. Always consult the [Travis CI](https://travis-ci.org/crossterm-rs/crossterm/pull_requests) build logs.
### Disallowed warnings ### Forbidden Warnings
Search for `#![deny(...)]` in the code: Search for `#![deny(...)]` in the code: