234 lines
8.6 KiB
Markdown
234 lines
8.6 KiB
Markdown
# Contributing to Lighthouse
|
|
|
|
[](https://gitter.im/sigp/lighthouse?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
|
|
|
|
Lighthouse is an open-source Ethereum Serenity client built in
|
|
[Rust](https://www.rust-lang.org/).
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
We've bundled up our Goals, Ethos and Ideology into one document for you to
|
|
read through, please read our [About Lighthouse](lighthouse.md) docs. :smile:
|
|
|
|
Layer-1 infrastructure is a critical component for the ecosystem and relies
|
|
heavily on contributions from the community. Building Ethereum Serenity is a
|
|
huge task and we refuse to conduct an inappropriate ICO or charge licensing
|
|
fees. Instead, we fund development through grants and support from Sigma
|
|
Prime.
|
|
|
|
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.
|
|
|
|
**Pre-reading Materials:**
|
|
|
|
* [About Lighthouse](lighthouse.md)
|
|
* [Ethereum Serenity](serenity.md)
|
|
|
|
**Repository**
|
|
|
|
If you'd like to contribute, try having a look through the [open
|
|
issues](https://github.com/sigp/lighthouse/issues) (tip: look for the [good
|
|
first
|
|
issue](https://github.com/sigp/lighthouse/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
|
|
tag) and ping us on the [gitter](https://gitter.im/sigp/lighthouse) channel. We need
|
|
your support!
|
|
|
|
## 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:)
|
|
|
|
Read through our [Understanding
|
|
Serenity](https://github.com/sigp/lighthouse/blob/master/docs/serenity.md) docs
|
|
to learn more! :smile: (*unless you've already read it.*)
|
|
|
|
The document explains the necessary fundamentals for understanding Ethereum,
|
|
Proof-of-Stake and the Serenity we are working towards.
|
|
|
|
## 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 meaningful 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**: Metadata 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**
|
|
|
|
*"A function is not considered complete until tests exist for it."*
|
|
|
|
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 | Trailing 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,
|
|
}
|
|
```
|