diff --git a/docs/onboarding.md b/docs/onboarding.md index 61ed1e07d..90b38df97 100644 --- a/docs/onboarding.md +++ b/docs/onboarding.md @@ -1,36 +1,286 @@ -# Learn how to contribute to ETH 2.0! +# Contributing to Lighthouse -Lighthouse is an Ethereum 2.0 client built in Rust. +Lighthouse is an open-source Ethereum Serenity client built in +[Rust](https://www.rust-lang.org/). -If you are interested in contributing to the Ethereum ecosystem, and you want to learn Rust, Lighthouse is a great project to work on. +Lighthouse welcomes all contributions with open arms. If you are interested in +contributing to the Ethereum ecosystem, and you want to learn Rust, Lighthouse +is a great project to work on. -Initially this doc will contain reading material to help get you started in Rust and Ethereum. Eventually it will have guides specific to Lighthouse. +This documentation aims to provide a smooth on-boarding for all who wish to +help contribute to Lighthouse. Whether it is helping with the mountain of +documentation, writing extra tests or developing components, all help is +appreciated and your contributions will help not only the community but all +the contributors. -## Learn Rust +If you have any additional questions, please feel free to jump on the +[gitter](https://gitter.im/sigp/lighthouse) and have a chat with all of us. -* [The Rust Programming Language](https://doc.rust-lang.org/book/2018-edition/index.html) -* [Learning Rust With Entirely Too Many Linked Lists](http://cglab.ca/~abeinges/blah/too-many-lists/book/) -* [Rustlings](https://github.com/rustlings/rustlings) - Small exercises to get you used to reading and writing Rust code. -* [Rust Exercism](https://exercism.io/tracks/rust) - 88 exercises to learn Rust. +## Ideology -## Learn Ethereum +### Never Panic + +Lighthouse will be the gateway interacting with the Proof-of-Stake system +employed by Ethereum. This requires the validation and proposal of blocks +and extremely timely responses. As part of this, Lighthouse aims to ensure +the most uptime as possible, meaning minimising the amount of +exceptions and gracefully handling any issues. + +Rust's `panic` provides the ability to throw an exception and exit, this +will terminate the running processes. Thus, Lighthouse aims to use `panic` +as little as possible to minimise the possible termination cases. + +### Security First Mindset + +Lighthouse aims to provide a safe, secure Serenity client for the Ethereum +ecosystem. At each step of development, the aim is to have a security-first +mindset and always ensure you are following the safe, secure mindset. When +contributing to any part of the Lighthouse client, through any development, +always ensure you understand each aspect thoroughly and cover all potential +security considerations of your code. + +### Functions aren't completed until they are tested + +As part of the Security First mindset, we want to aim to cover as many distinct +cases. A function being developed is not considered "completed" until tests +exist for that function. The tests not only help show the correctness of the +function, but also provide a way for new developers to understand how the +function is to be called and how it works. + +## Understanding Serenity + +Ethereum's Serenity is based on a Proof-of-Stake based sharded beacon chain. + +(*If you don't know what that is, don't `panic`, that's what this documentation +is for!* :smile:) + +### Ethereum + +Ethereum is an open blockchain protocol, allowing for the building and use of +decentralized applications that run on blockchain technology. The blockchain can +be seen as a decentralized, distributed ledger of transactions. + +General Ethereum Introduction: -#### General Ethereum Resources * [What is Ethereum](http://ethdocs.org/en/latest/introduction/what-is-ethereum.html) * [Ethereum Introduction](https://github.com/ethereum/wiki/wiki/Ethereum-introduction) -#### Ethereum 2.0 -* [Ethereum 2.0 Spec - Casper and Sharding](https://github.com/ethereum/eth2.0-specs/blob/master/specs/beacon-chain.md) -#### Sharding +### Proof-of-Work and the current state of Ethereum. -* [How to Scale Ethereum: Sharding Explained](https://medium.com/prysmatic-labs/how-to-scale-ethereum-sharding-explained-ba2e283b7fce) +Currently, Ethereum is based on the Proof-of-Work model, a Sybil resilient +mechanism to allow nodes to propose blocks to the network. Although it provides +properties that allow the blockchain to operate in an open, public +(permissionless) network, it faces it's challenges and as a result impacts +the operation of the blockchain. -#### Casper +The main goals to advance Ethereum is to (1) increase the scalability and +overall transaction processing power of the Ethereum world computer and (2) +find a suitable replacement for Proof-of-Work that still provides the necessary +properties that we need. -* [Proof of Stake - Casper FFG](https://www.youtube.com/watch?v=uQ3IqLDf-oo) -* [Beacon Casper Chain](https://www.youtube.com/watch?v=GAywmwGToUI) +* [Proof-of-Work in Cryptocurrencies: an accessible introduction](https://blog.sigmaprime.io/what-is-proof-of-work.html) -### TODO -- add reading material as we discover. -- start developing guides specific to lighthouse. +### Serenity + +As part of the original Ethereum roadmap +[\[1\]](https://blog.ethereum.org/2015/03/03/ethereum-launch-process/) +[\[2\]](http://ethdocs.org/en/latest/introduction/the-homestead-release.html), +the Proof-of-Stake integration falls under **Release Step 4:*Serenity***. With +this, a number of changes are to be made to the current Ethereum protocol to +incorporate some of the new Proof-of-Stake mechanisms as well as improve on +some of the hindrances faced by the current Proof-of-Work chain. + +To now advance the current Ethereum, the decision is made to move to a sharded +Beacon chain structure where multiple shard-chains will be operating and +interacting with a central beacon chain. + +(Be mindful, the specifications change occasionally, so check these to keep up +to date) + +* Current Specifications: + * [Danny Ryan's "State of the Spec"](https://notes.ethereum.org/s/BJEZWNoyE) (A nice summary of the current specifications) + * [Ethereum Serenity - Phase 0: Beacon Chain Spec](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md) + * [Ethereum Serenity - Phase 1: Sharded Data Chains](https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/1_shard-data-chains.md) + * [Beacon Chain - Vitalik Buterin and Justin Drake explain](https://www.youtube.com/watch?v=GAywmwGToUI) +* Understanding Sharding: + * [Prysmatic Labs: Sharding Explained](https://medium.com/prysmatic-labs/how-to-scale-ethereum-sharding-explained-ba2e283b7fce) +* Other relevant resources + * [Proof of Stake - Casper FFG](https://www.youtube.com/watch?v=uQ3IqLDf-oo) + +## Development Onboarding + +If you would like to contribute and develop Lighthouse, there are only a few +things to go through (and then you're on your way!). + +### Understanding Rust + +Rust is an extremely powerful, low-level programming language that provides +freedom and performance to create powerful projects. The [Rust +Book](https://doc.rust-lang.org/stable/book/) provides insight into the Rust +language and some of the coding style to follow (As well as acting as a great +introduction and tutorial for the language.) + +Rust has a steep learning curve, but there are many resources to help you! + +* [Rust Book](https://doc.rust-lang.org/stable/book/) +* [Rust by example](https://doc.rust-lang.org/stable/rust-by-example/) +* [Learning Rust With Entirely Too Many Linked Lists](http://cglab.ca/~abeinges/blah/too-many-lists/book/) +* [Rustlings](https://github.com/rustlings/rustlings) +* [Rust Exercism](https://exercism.io/tracks/rust) +* [Learn X in Y minutes - Rust](https://learnxinyminutes.com/docs/rust/) + + +#### Getting Started and installing Rust + +We recommend installing Rust using [**rustup**](https://rustup.rs/). Rustup +allows you to easily install versions of rust. + +**Linux/Unix/Mac:** + +``` +$ curl https://sh.rustup.rs -sSf | sh +``` + +**Windows (You need a bit more):** + +* Install the Visual Studio 2015 with C++ support +* Install Rustup using: https://static.rust-lang.org/rustup/dist/x86_64-pc-windows-msvc/rustup-init.exe +* You can then use the ``VS2015 x64 Native Tools Command Prompt`` and run: + +``` +rustup default stable-x86-64-pc-windows-msvc +``` + +#### Getting ready with Cargo + +[Cargo](https://doc.rust-lang.org/cargo/) is the package manager for Rust, and +allows to extend to a number of packages and external libraries. It's also extremely +handy for handling dependencies and helping to modularise your project better. + +*Note: If you've installed rust through rustup, you should have ``cargo`` +installed.* + + +#### Rust Terminology + +When developing rust, you'll come across some terminology that differs to +other programming languages you may have used. + +* **Trait**: A trait is a collection of methods defined for a type, they can be +implemented for any data type. +* **Struct**: A custom data type that lets us name and package together +multiple related values that make a meaninguful group. +* **Crate**: A crate is synonymous with a *library* or *package* in other +languages. They can produce an executable or library depending on the +project. +* **Module**: A collection of items: functions, structs, traits, and even other +modules. Modules allow you to hierarchically split code into logical units +and manage visibility. +* **Attribute**: Metadaata applied to some module, crate or item. +* **Macros**: Macros are powerful meta-programming statements that get expanded +into source code that gets compiled with the rest of the code (Unlike `C` +macros that are pre-processed, Rust macros form an Abstract Syntax Tree). + + +Other good appendix resources: + +* [Keywords](https://doc.rust-lang.org/book/appendix-01-keywords.html) +* [Operators/Symbols](https://doc.rust-lang.org/book/appendix-02-operators.html) +* [Traits](https://doc.rust-lang.org/book/appendix-03-derivable-traits.html) + + +### Understanding the Git Workflow + +Lighthouse utilises git as the primary open-source development tool. To help +with your contributions, it is great to understand the processes used to ensure +everything remains in sync and there's as little conflict as possible when +working on similar files. + +Lighthouse uses the **feature branch** workflow, where each issue, or each +feature, is developed on its own branch and then merged in via a pull-request. + +* [Feature Branch Tutorial](https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow) + +## Code Conventions/Styleguide and Ethos + +### Ethos + +**Pull Requests** + +Pull requests should be reviewed by **at least** one "*core developer*" +(someone with write-access to the repo). This should ensure bugs are caught and +the code is kept in a consistent state that follows all conventions and style. + +All discussion (whether in PRs or Issues or in the Gitter) should be respectful +and intellectual. Have fun, but always respect the limits of other people. + +**Testing** + +Generally, tests can be self-contained in the same file. Integration tests +should be added into the ``tests/`` directory in the crate's **root**. + +Large line-count tests should be in a separate file. + +### Rust StyleGuide + +Lighthouse adheres to Rust code conventions as outlined in the [**Rust +Styleguide**](https://github.com/rust-dev-tools/fmt-rfcs/blob/master/guide/guide.md). + +Ensure you use [Clippy](https://github.com/rust-lang/rust-clippy) to lint and +check your code. + +| Code Aspect | Guideline Format | +|:--------------------|:-------------------------------| +| Types | ``UpperCamelCase`` | +| Enums/Enum Variants | ``UpperCamelCase`` | +| Struct Fields | ``snake_case`` | +| Function / Method | ``snake_case`` | +| Macro Names | ``snake_case`` | +| Constants | ``SCREAMING_SNAKE_CASE`` | +| Forbidden name | Trialing Underscore: ``name_`` | + +Other general rust docs: + +* [Rust Other Style Advice](https://github.com/rust-dev-tools/fmt-rfcs/blob/master/guide/advice.md) +* [Cargo.toml Conventions](https://github.com/rust-dev-tools/fmt-rfcs/blob/master/guide/cargo.md) + +### TODOs + +All `TODO` statements should be accompanied by a GitHub issue. + +```rust +pub fn my_function(&mut self, _something &[u8]) -> Result { + // TODO: something_here + // https://github.com/sigp/lighthouse/issues/XX +} +``` + +### Comments + +**General Comments** + +* Prefer line (``//``) comments to block comments (``/* ... */``) +* Comments can appear on the line prior to the item or after a trailing space. +```rust +// Comment for this struct +struct Lighthouse {} + +fn make_blockchain() {} // A comment on the same line after a space +``` + +**Doc Comments** + +* The ``///`` is used to generate comments for Docs. +* The comments should come before attributes. + +```rust +/// Stores the core configuration for this Lighthouse instance. +/// This struct is general, other components may implement more +/// specialized config structs. +#[derive(Clone)] +pub struct LighthouseConfig { + pub data_dir: PathBuf, + pub p2p_listen_port: u16, +} +```