Merge pull request #104 from TimonPost/docs

fhaynes · web-flow · commit f10a8b0c717c · 2018-11-12T11:48:59.000-08:00
Added styleguides and release notes doc also improved readme.md
diff --git a/Cargo.toml b/Cargo.toml
@@ -9,6 +9,7 @@ authors = [
 description = "A simple semi-reliable UDP protocol for multiplayer games"
 keywords = ["gamedev", "networking", "udp", "amethyst"]
 categories = ["game-engines", "network-programming"]
+exclude = ["examples/*", "docs/*", "benches/*"]
 
 readme = "README.md"
 license = "MIT/Apache-2.0"
diff --git a/README.md b/README.md
@@ -15,70 +15,80 @@
 [s6]: https://tokei.rs/b1/github/amethyst/laminar?category=code
 [s7]: https://codecov.io/gh/amethyst/laminar/branch/master/graphs/badge.svg
 
-A UDP-based protocol that provides partial reliability. Coming soon!
+This library implements some TCP-like features on top of an UDP-socket. 
+It will provide a lightweight message-based interface with certain guarantees like reliability, fragmentation congestion monitoring.
 
-## Note
+Laminar was designed to be used in the [Amethyst][amethyst] game engine and is loosely based on articles from [gaffer on games](https://gafferongames.com/).
 
-This library is not yet stable. It is experimental and things may change frequently.
+[amethyst]: https://github.com/amethyst/amethyst
 
 ## Table of contents:
-- [Useful links](https://github.com/amethyst/laminar#useful-links)
-- [Features](https://github.com/amethyst/laminar#features)
-- [Examples](https://github.com/amethyst/laminar#examples)
-    - [Udp](https://github.com/amethyst/laminar#udp)
-- [Notice](https://github.com/amethyst/laminar#notice)
-- [Contributing](https://github.com/amethyst/laminar#contributing)
-- [Authors](https://github.com/amethyst/laminar/#authors)
+- [Useful links](#useful-links)
+- [Features](#features)
+- [Getting Started](#getting-stated)
+- [Examples](#examples)
+- [Notice](#notice)
+- [Contributing](#contribution)
+- [Authors](#authors)
 - [License](#license)
 
+## Features
+These are the features this crate provides:
+
+- UDP-based protocol
+- Connection tracking
+- Automatic Fragmentation
+- Unreliable and Reliable packets
+- Protocol versioning
+- RTT estimation
+- Link conditioner to simulate packet loss and latency
+- Well tested by integration tests and unit tests
+- Good error handling
+- Benchmarks
+
+## Getting Stated
 Add the laminar package to your `Cargo.toml` file.
 
 ```toml
 [dependencies]
-laminar = "0.0.0"
+laminar = "0.1"
 ```
-And import the laminar modules you want to use.
 
-```rust
-extern crate laminar;
-
-// this module contains all socket related logic.
-use laminar::net::{UdpSocket, SocketAddr, NetworkConfig, Connection, Quality};
-// this module contains packet related logic.
-use laminar::packet::{Packet};
-```
-
-## Useful Links
+### Useful Links
 
 - [Documentation](https://docs.rs/laminar/).
-- [Cargo Page](https://crates.io/crates/laminar)
+- [Crates.io](https://crates.io/crates/laminar)
 - [Examples](https://github.com/amethyst/laminar/tree/master/examples)
-
-## Features
-These are the features from this crate:
-
-- Semi-reliable UDP
-- Fragmentation
-- RTT estimation
-- Virtual connection management.
+- [Contributing](https://github.com/amethyst/laminar/blob/master/docs/CONTRIBUTING)
 
 ## Examples
-These are some basic examples demonstrating how to use this crate. See [examples](https://github.com/amethyst/laminar/tree/master/examples) for more.
+These are some basic examples demonstrating how to use this crate. 
+Please checkout our [examples](https://github.com/amethyst/laminar/tree/master/examples) for more.
 
-### Udp API | [see more](https://github.com/amethyst/laminar/blob/master/examples/udp.rs)
+### UDP API | [see more](https://github.com/amethyst/laminar/blob/master/examples/udp.rs)
 This is an example of how to use the UDP API.
 
 _Send packets_
 
 ```rust
+use laminar::{DeliveryMethod, Packet};
+use laminar::net::{UdpSocket, NetworkConfig};
+
 // Create the necessarily config, you can edit it or just use the default.
 let config = NetworkConfig::default();
 
 // Setup an udp socket and bind it to the client address.
 let mut udp_socket = UdpSocket::bind("127.0.0.1:12346", config).unwrap();
 
+// our data
+let bytes = vec![...];
+
 // Create a packet that can be send with the given destination and raw data.
-let packet = Packet::new(destination, vec![1,2,3]);
+let packet = Packet::new(destination, bytes, DeliveryMethod::Unreliable);
+
+// Or we could also use the function syntax for more clarity:
+let packet = Packet::unreliable(destination, bytes);
+let packet = Packet::reliable_unordered(destination, bytes);
 
 // Send the packet to the endpoint we earlier placed into the packet.
 udp_socket.send(packet);
@@ -87,13 +97,15 @@ udp_socket.send(packet);
 _Receive Packets_
 
 ```rust
+use laminar::net::{UdpSocket, NetworkConfig};
+use std::net::SocketAddr;
 // Create the necessarily config, you can edit it or just use the default.
 let config = NetworkConfig::default();
 
 // Setup an udp socket and bind it to the client address.
 let mut udp_socket = UdpSocket::bind("127.0.0.1:12345", config).unwrap();
 
-// Start receiving (blocks the current thread)
+// Start receiving (blocks the current thread), use `udp_socket.set_nonblocking()` for not blocking the current thread.
 let result = udp_socket.recv();
 
 match result {
@@ -124,6 +136,12 @@ match result {
 
 We want to give credit to [gaffer on games](https://gafferongames.com/) as we have used his guide to building a game networking protocol to build this library. 
 
+## Note
+
+This library is not fully stable yet. 
+Although version 0.1.0 is released we might have to change some of the existing API.  
+Laminar is used in [Amethyst-Network](https://github.com/amethyst/amethyst/tree/master/amethyst_network), you could give that a look if you want to see some more advanced use-cases.
+
 ## Contribution
 
 Unless you explicitly state otherwise, any contribution intentionally submitted
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
@@ -0,0 +1,21 @@
+# Change Log
+This document contains information about the releases of this crate.
+
+## [0.1.0] - 2018-11-12
+The Networking team is happy to announce the release of `0.1.0`` of the [laminar crate](https://github.com/amethyst/laminar). 
+It provides UDP networking modified for the needs of game networking. 
+Most of the techniques used were published and detailed by [Glenn Fiedler](https://gafferongames.com/). 
+We’d like to extend a special thanks to him and his articles.
+
+### Added 
+
+- UDP-based protocol
+- Automatic Fragmentation
+- RTT estimation
+- Connection tracking
+- Unreliable and Reliable sending of packets
+- Protocol version monitoring
+- A link conditioner to simulate packet loss and latency
+- Good error handling with **zero** panics
+- Well tested by integration and unit tests
+- Benchmarks
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -0,0 +1,42 @@
+## Workflow
+
+As a team, we adopted the following the workflow agreements. When we begin work on the amethyst_network crate, we’ll use the same agreements. They are focused on maintaining a high level of quality in the code, and for working with a highly distributed team. We’re including them here as some of the other teams may find them of use.
+
+- All warnings produced by `cargo test` are treated as errors by the CI/CD system
+- All `clippy` warnings are treated as errors by the CI/CD system
+- We use `kcov` to track our code coverage; we do not have a required minimum, rather we use this as a potential indicator of issues
+- We included sample code about using the library
+- Setting up a benchmarking framework so we can track regressions
+- Unit and integration tests, as well as release testing with docker-compose
+
+## Style Guidelines
+
+As a team, we (eventually) agreed on a coherent style for all our work. See this [document](https://github.com/amethyst/laminar/blob/master/docs/CONTRIBUTING.md#code-style) for more information.
+Some of the most helpful ones have been:
+
+- Keep PRs small, preferably under 200 lines of code when possible
+- Comments should explain why, not what
+- You must provide comments for public API
+- No hard-coded values
+- No panics nor unwraps in non-test code
+- `rustfmt` stable release must be used
+- `rustfmt` should be done as its own PR, to avoid generating giant PRs that are impossible to review
+- We make use of the [forking workflow](https://nl.atlassian.com/git/tutorials/comparing-workflows/forking-workflow)
+
+## Code style
+
+Some code guidelines to keep in mind when contributing to laminar or amethyst-networking
+1. Comments
+    - Comment all code you’ve added. Things you should comment: types, methods/functions public fields of structs. 
+    - Calculations should be documented. Whether it would be in a PR or code. But it must be clear what is done.
+    - Public things should get docstring comments using `///`. Non-public things may use `//` comments
+    - Keep comments small
+    - Don’t create unnecessary comments. They must add value
+    - Comments should explain the “why” not the “what”
+2. Hard Coding
+    - Don't hard code values anywhere
+    - Use the ‘NetworkConfig’ type for common network settings, use consts or parameter input
+    - Use of lazy_static is acceptable but first make sure you can’t fix the issue in other ways
+3. Code markup
+    - Keep files small. Better have small files with small pieces of logic than having one file with 1000 lines of logic with multiple types/structs etc. Note that I speak of logic, tests not included
+	- No panics/unwraps in the main codebase, but they are accepted in tests
diff --git a/docs/FEATURES.md b/docs/FEATURES.md
@@ -0,0 +1,18 @@
+# Features
+These are all the features we have and don't have. 
+## Added
+
+* [x] Fragmentation
+* [x] Unreliable packets
+* [x] Reliable unordered packets
+* [x] Fragmentation
+* [x] Rtt estimations
+* [x] Protocol version monitoring
+* [x] Virtual connection management
+
+## Planned
+
+* [ ] Reliable Ordered packets
+* [ ] Unreliable Ordered packets
+* [ ] Sequenced packets
+* [ ] Cryptography
diff --git a/src/lib.rs b/src/lib.rs
@@ -1,5 +1,5 @@
 //! Laminar semi-reliable UDP protocol for multiplayer games. This library implements wraps around a UDP
-//! and provides light weight stream based interface that provides certain guarentees like reliablity.
+//! and provides light weight stream based interface that provides certain guarantees like reliability.
 //!
 //! Laminar was designed to be used within the [Amethyst][amethyst] game engine.
 //!
