Start #93; Update documentation.
This commit is contained in:
Chris Natoli
parent
7ced7aee89
commit
4cb2efb042
@ -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<String, Error> {
|
||||
// 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,
|
||||
}
|
||||
```
|
||||
|
||||
Loading…
Reference in New Issue
Block a user