lighthouse/docs/ONBOARDING.md

Contributing to Lighthouse

Lighthouse is an open-source Ethereum Serenity client built in Rust.

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 docs. 😄

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 and have a chat with all of us.

Pre-reading Materials:

• About Lighthouse
• Ethereum Serenity

Repository

If you'd like to contribute, try having a look through the open issues (tip: look for the good first issue tag) and ping us on the gitter 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! 😄)

Read through our Understanding Serenity docs to learn more! 😄 (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 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
• Rust by example
• Learning Rust With Entirely Too Many Linked Lists
• Rustlings
• Rust Exercism
• Learn X in Y minutes - Rust

Getting Started and installing Rust

We recommend installing Rust using rustup. 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 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
• Operators/Symbols
• Traits

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

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.

Ensure you use 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
• Cargo.toml Conventions

TODOs

All TODO statements should be accompanied by a GitHub issue.

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.

// 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.

/// 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,
}