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)
|
## Ideology
|
||||||
* [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.
|
|
||||||
|
|
||||||
## 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)
|
* [What is Ethereum](http://ethdocs.org/en/latest/introduction/what-is-ethereum.html)
|
||||||
* [Ethereum Introduction](https://github.com/ethereum/wiki/wiki/Ethereum-introduction)
|
* [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)
|
* [Proof-of-Work in Cryptocurrencies: an accessible introduction](https://blog.sigmaprime.io/what-is-proof-of-work.html)
|
||||||
* [Beacon Casper Chain](https://www.youtube.com/watch?v=GAywmwGToUI)
|
|
||||||
|
|
||||||
### TODO
|
### Serenity
|
||||||
- add reading material as we discover.
|
|
||||||
- start developing guides specific to lighthouse.
|
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