Refactor/contributor content (#126)
* removed CLI Styleguide images to wiki. * docs contributor content refactor: * updated README * simplified CONTRIBUTING.md * removed unecessary root MD files * Links to Docs Wiki section * added removed image file + url link unification * LF wording and links * wording improvement * removed rule from link_check_conf.json * deleted docs/community and moved content over to wiki * formatting and contributing wiki link * small typo and config update * fixed links Signed-off-by: Felipe Faraggi <felipefaraggi@gmail.com>pull/143/head 1.4.0-beta3
Felipe Faraggi
5 years ago
committed by
GitHub
parent
cbe9be1eb3
commit
4d543d1a88
@ -1,246 +0,0 @@ |
||||
# Besu Command Line Interface (CLI) Style Guide |
||||
|
||||
## Purpose of this Document |
||||
|
||||
This document contains guidelines to help the Besu command line interface (CLI) remain usable, modular, and extensible as it grows over time. This is a living document and should evolve to better suit end users and those who contribute to Besu. |
||||
|
||||
> **Note:** Although not every pattern shown in this style guide is currently followed in Besu, it is our intention to revise and build new functionality with these guidelines in mind. |
||||
|
||||
**The primary audience for this document is:** |
||||
|
||||
* Members of the Besu team |
||||
* Developers contributing pull requests |
||||
|
||||
## Mission Statement |
||||
|
||||
The Besu CLI should create a consistent and easy to understand experience for end users. We're focused on creating a great developer experience for both new and expert users of Ethereum clients. |
||||
|
||||
## General Guidelines |
||||
|
||||
There are four guiding principles for the Besu CLI to help us create a good developer experience for both new and expert users: **_(1) be consistent, (2) keep it simple, (3) be proactive, and (4) be informative (to people and machines)._** |
||||
|
||||
This section outlines what each of these principles mean and the following sections explain how these principles should be applied in specific scenarios. |
||||
|
||||
### 1. Be Consistent |
||||
Consistency is important to help our end users build a mental model of how Besu works. By being consistent with our word choices, visual formatting, and style of communication it helps users know what to expect as they interact with Besu. |
||||
|
||||
### 2. Keep it Simple |
||||
Avoid technical jargon and always assume our end users may have questions. This doesn't mean answering all of those questions in the CLI, but it does mean explaining things in a simple way and when complexity inevitably rises, directing our users to documentation that will help them. |
||||
|
||||
### 3. Be Proactive |
||||
Being proactive means anticipating user needs and guiding them through a process. This most often takes the form of solution-oriented warning/error messages. Put yourself in the user's shoes and consider what questions you would have every time we are showing feedback or status to them. |
||||
|
||||
### 4. Be Informative (to people and machines) |
||||
We seek a balance between providing enough relevant information to help our users develop a solid mental model of how Besu works without forcing them to read too much text. In addition, it is important we consider not only the end user of the CLI but to be consistent with formatting and feedback so information is easily interpreted by machines. |
||||
|
||||
## User Input & Actions |
||||
|
||||
### **Subcommands** |
||||
A subcommand is an action that can be taken on a single object (i.e. import, export, delete, etc.). |
||||
|
||||
#### **Formatting and Grammar** |
||||
* Commands should follow a noun-verb dialogue. This takes the form of `object action` in most cases. |
||||
* Separate the object and action with a space. |
||||
* If there is no easy way to avoid multiple words within an object or action, use a dash to separate the words (i.e. word1-word2). |
||||
* Use commonly understood words (import, export, list, delete, add, etc.). |
||||
* Be consistent with what words are already being used in other subcommands. |
||||
|
||||
**Examples:** |
||||
|
||||
`besu blocks import` |
||||
|
||||
`besu public-key export` |
||||
|
||||
Although noun-verb formatting seems backwards from a speaking perspective (i.e. blocks import vs. import blocks) it allows us to organize commands the same way users think about completing an action (the topic first, then the action). |
||||
|
||||
|
||||
#### **Inputs** |
||||
|
||||
Using required options instead of arguments helps users have a clear understanding of the impact of an action. Inputs are most often verbs (from, to, etc.). Other options avoid the use of verbs to help make this distinction. |
||||
|
||||
**Example:** `besu blocks import --from=<FILE>` |
||||
|
||||
Requiring the `--from` option makes it clear where you are importing from. In the case of a single parameter (as shown in the example above) we should also accept this as an argument (`besu blocks import <FILE>`). Although we accept this formatting, it is not encouraged and should be excluded from our documentation. |
||||
|
||||
### Flags |
||||
|
||||
Flags are boolean and turn on or off some behavior. |
||||
|
||||
**Formatting and Grammar** |
||||
|
||||
* Each flag should end with "enabled" regardless of the initial state to keep things consistent. |
||||
* Each state should be supported in the CLI regardless of the default value in order to override a flag set in the configuration file. |
||||
* Do not combine words, instead use a dash to separate them (i.e. `--word1-word2-enabled`). |
||||
|
||||
**Examples:** |
||||
|
||||
If “foo” is disabled by default, `--foo-enabled` or `--foo-enabled=true` would turn it on. |
||||
|
||||
If “foo” is enabled by default, `--foo-enabled=false` would turn it off. |
||||
|
||||
**Use Smart Defaults** |
||||
|
||||
Always take security into consideration when deciding the default value of a flag. If a flag will be enabled for the majority of use cases and there are no security concerns, it should be enabled by default. Otherwise, it should be disabled. |
||||
|
||||
|
||||
### Options |
||||
|
||||
Options are used for settings, like specifying a configuration file or to provide input to a subcommand. |
||||
|
||||
**Formatting and Grammar** |
||||
|
||||
* Always separate words with a dash and do not combine words even if it adds to the overall character count. |
||||
* Avoid using verbs in option names unless they specify an input for a subcommand. |
||||
* Specify what the expected value is at the end of the option (i.e. `--config-file` vs. `--config)`. |
||||
|
||||
**Example:**`--option-file=<VALUE>` |
||||
|
||||
|
||||
## Adding New Inputs |
||||
|
||||
|
||||
### General Naming Guidelines |
||||
|
||||
Words matter. Most users will not be interacting with Besu on a regular basis so we should name things for ease of understanding. |
||||
|
||||
* Don't use abbreviations unless they are widely understood. Optimize for understanding, not number of characters. |
||||
|
||||
* Consider existing word choices in other Ethereum clients and follow their lead if it makes sense. |
||||
|
||||
* When using words from other clients, make sure to use them in the EXACT same context to avoid confusion. |
||||
|
||||
* Consider what "group" a new addition will fit in when displayed on the `--help` screen. Follow the patterns that are already being used to keep things consistent. |
||||
|
||||
> **Note:** Grouping of options on the `--help` screen does not currently exist. |
||||
|
||||
|
||||
### Developer vs. End User |
||||
|
||||
In general, creating hidden functionality is not ideal. However, if a new subcommand, flag or option has been created specifically for development purposes and has minimal use for end users, begin the name with `--X` to indicate it's temporary and should not be documented. |
||||
|
||||
|
||||
### Consider Dependent Settings |
||||
|
||||
No command, flag or option exists in a vacuum. The user is trying to accomplish a task and we should keep their entire workflow in mind as new things are added. Things to consider are: |
||||
|
||||
* What other options or flags may be impacted. Can they be combined to avoid extra work for the user and keep our documentation simple? |
||||
* What error, success or warning messages need to be added to ensure the user has a clear understanding of what happened and what their next steps may be? |
||||
|
||||
## Responding to User Input |
||||
|
||||
> **Note:** The patterns and functionality in this section are not currently implemented. |
||||
|
||||
Feedback to the user should always be clear, concise and avoid technical jargon. We use color and clear labels to help imply meaning. Color should only be used during TTY sessions and can be turned off with the `--color-enabled=false` flag. |
||||
|
||||
|
||||
### Input Warnings |
||||
|
||||
Warnings should be used when an option has been successfully set but there may be other factors the user should take into consideration. |
||||
|
||||
 |
||||
|
||||
**Color/text formatting:** |
||||
|
||||
* **"WARNING" Label:** Bold, Bright - Yellow - ANSI 33 |
||||
* **Warning Message:** Bright - Yellow - ANSI 33 |
||||
* **Additional Message (Optional):** No formatting |
||||
|
||||
There should be a clear line break before and after a warning to call attention to it. A second line containing more details or a potential solution is recommended but optional. |
||||
|
||||
|
||||
### Input Errors |
||||
|
||||
When a value cannot be applied, show a clear error message and provide context on how the error can be avoided. |
||||
|
||||
 |
||||
|
||||
**Color/text formatting:** |
||||
|
||||
* **"ERROR" Label:** Bold, Red - ANSI 31 |
||||
* **Error Message:** Red - ANSI 31 |
||||
* **"Solution:" Label (Optional):** Bold |
||||
* **Solution Message (Optional):** No formatting |
||||
|
||||
There should be a clear line break before and after an error to help call attention to it. A second line containing a potential solution to fix the error is recommended but optional. |
||||
|
||||
If the error is caused by an unknown option, the following formatting should be followed: |
||||
|
||||
 |
||||
|
||||
## Logging in the CLI |
||||
|
||||
> **Note:** The patterns and functionality in this section are not currently implemented. |
||||
|
||||
Displaying process should be a balance between human readability and ease of interpretation by machines. We remain as consistent as possible between the information shown in the CLI and what will be included in logs. Having said that, we use color and progress indicators to help users easily scan and interpret the information we are showing them while a TTY session is active. This formatting is optional and can be turned off by the user if desired. |
||||
|
||||
|
||||
### Spacing, Alignment, & Visual Formatting |
||||
|
||||
Consistency in spacing is important for machines to easily interpret logs. Consistency in alignment and visual formatting is important for humans to easily scan and find relevant information. |
||||
|
||||
|
||||
#### General Format: |
||||
|
||||
`<timestamp> | <log level> | <thread> | <class> | <message>` |
||||
|
||||
|
||||
#### Color & Text Formatting: |
||||
|
||||
* **Timestamp:** Dimmed |
||||
* **Log Level - INFO:** Cyan - ANSI 96 |
||||
* **Log Level - ERROR:** Bold, Red - ANSI 31 |
||||
* **Log Level - WARNING:** Bold, Bright - Yellow - ANSI 33 |
||||
* **Info Message:** No formatting |
||||
* **Highlighted Information:** Green - ANSI 32 |
||||
* **Error Message:** Bold, Red - ANSI 31 |
||||
* **Warning Message:** Bold, Bright - Yellow - ANSI 33 |
||||
* **Failure Message:** Bold, Red - ANSI 31 |
||||
* **Failure Reasons:** Dimmed |
||||
* **Thread:** Cyan - ANSI 36 |
||||
* **Class:** Cyan - ANSI 36 |
||||
* **Vertical Bar Separator:** Dimmed |
||||
|
||||
Color and formatting is used to help users to easily scan and find relevant information. Cyan is our default color making it easy for users to ignore. This makes red and yellow stand out. Green is used selectively to help call attention to specific information or values in messages. |
||||
|
||||
|
||||
#### Spacing & Alignment: |
||||
|
||||
* Each piece of information is separated by a vertical bar. |
||||
* We keep consistent visual spacing between the log level and the thread/classes (7 spaces) so messages that relate to the same thread and class are visually grouped. |
||||
* **INFO** is followed by 3 spaces |
||||
* **ERROR** is followed by 2 spaces |
||||
* **WARNING** is followed by a single space |
||||
* Spacing and alignment is the same in the command line and logs to ensure users have a consistent experience. |
||||
|
||||
|
||||
### Information |
||||
|
||||
"Information" (i.e. "INFO") is status of what is currently happening or has happened. The lack of an error or warning indicates that things are running smoothly. Information should be output with "stdout". |
||||
|
||||
 |
||||
|
||||
### Error |
||||
|
||||
An "error" should be shown if a process cannot be completed. Errors should be output with "stderr". Errors should include a clear reason why the error has occurred. |
||||
|
||||
 |
||||
|
||||
### Warning |
||||
|
||||
A "warning" is shown when a process has been completed but it did not go as expected. Warnings should be output with "stderr". Warnings should include a clear reason why the warning has occured. |
||||
|
||||
 |
||||
|
||||
### Failure |
||||
|
||||
A "failure" should be shown if a process cannot be completed. Details about the failure should follow the main failure statement. Failures should be output with "stderr". |
||||
|
||||
 |
||||
|
||||
## Indicating Progress |
||||
|
||||
> **Note:** The patterns and functionality in this section are not currently implemented. |
||||
|
||||
We should always indicate that progress is being made so the user knows a process has not stalled. Progress indicators should only be included for TTY sessions (not in output) and can be turned off with the `--progress-enabled=false` flag. The progress indicator should appear on a new line below the last line of information. Once the process is complete, the progress indicator will move down to the next empty line. A progress indicator is not needed if a process takes less than a second. |
||||
|
||||
 |
||||
@ -1,224 +0,0 @@ |
||||
# Contents |
||||
* [1 Introduction](#1-introduction) |
||||
* [2 General Design Philosophy](#2-general-design-philosophy) |
||||
* [3 Specific Design Techniques](#3-specific-design-techniques) |
||||
* [4 Java](#4-java) |
||||
* [5 Logging](#5-logging) |
||||
|
||||
# 1 Introduction |
||||
|
||||
This document contains guidelines (some stricter than others) so we can be consistent and spend more time solving the bigger and more interesting issues. |
||||
|
||||
The guidelines are intended to facilitate working together not to facilitate reviews that criticize without adding value. |
||||
|
||||
Some guidelines are personal opinion. The idea being we make a decision once, document it, and apply it for consistency. Again, we can then spend more time on the interesting issues and less time discussing coding conventions :-) |
||||
|
||||
# 2 General Design Philosophy |
||||
|
||||
The key principles are: |
||||
* Keep It Simple |
||||
* Idiomatic Java |
||||
* YAGNI (You Ain't Gonna Need It) |
||||
|
||||
## 2.1 Keep It Simple |
||||
|
||||
Simple does not mean the fewest lines of code. Simple code is: |
||||
* Easy to understand |
||||
* Self-documenting and not dependent on comments to explain what it does |
||||
* Understandable even to inexperienced Java developers |
||||
* Dependent on selecting the right data structures for the task |
||||
* Usually the most performant. Without data showing another approach is faster, stick with the simple design |
||||
* Not simplistic: |
||||
|
||||
- Ethereum is complex and Besu must handle this complexity and operate correctly and securely |
||||
- Besu code should align with well-established Ethereum abstractions and terminology used in Ethereum specifications |
||||
- Aim to make the code as simple as possible but no simpler |
||||
|
||||
## 2.2 Idiomatic Java |
||||
|
||||
Besu embraces typical Java idioms including using an Object Oriented approach to design. This includes: |
||||
* Providing alternate behaviours via polymorphism instead of having conditional logic scattered through the codebase. For example, `ProtocolSpec` provides a standard interface to blockchain operations and multiple implementations define the different behaviours for each Ethereum milestone. |
||||
* Encapsulating behaviour and data together in classes. For example, `BytesValue` encapsulates byte data and methods operating on the byte data. `BytesValue.isZero()` is an instance method instead of accepting a `BytesValue` parameter. |
||||
|
||||
`ProtocolSpec` is an exception and does not hold the blockchain data on which it operates. This is because that blockchain data is widely shared and not specifically owned by `ProtocolSpec`. |
||||
* Embracing modern Java features like Optional, Streams and lambdas when they make code simpler and clearer. |
||||
|
||||
- Do use Streams and map with lambdas to convert values in a list to a different form. |
||||
- Don't pass lambdas into executors because it makes it harder to identify the threading interactions. The lambda makes the code shorter but not clearer. Instead use a separate class or extract a method. |
||||
* For good examples, refer to the APIs the JDK itself exposes. |
||||
|
||||
>**Note** If you're not sure what idiomatic Java looks like, start by following the typical patterns and naming used in Besu. |
||||
|
||||
## 2.3 You Ain't Gonna Need It (YAGNI) |
||||
|
||||
The Besu design prioritizes meeting current requirements in the simplest, clearest way over attempting to anticipate future functionality. As a result, Besu’s design: |
||||
* Is not set in stone as a big upfront design. The design is adjusted through constant refactoring as new requirements are added and understood. |
||||
* Uses abstraction only where it aids understanding of the current code. Abstraction is not used where it only supports future needs. |
||||
* Avoids over-engineering. |
||||
|
||||
# 3 Specific Design Techniques |
||||
|
||||
# 3.1 Creating Understandable, Self-documenting Code |
||||
|
||||
To create understandable, self-documenting code: |
||||
- Use clear naming for variables, methods, and classes |
||||
- Use US spelling instead of UK. For example, synchronize instead of synchronise |
||||
- Keep methods and classes short and focused on a single responsibility. Preferable maximum lengths: |
||||
* Lambdas: 1 - 3 lines |
||||
* Methods: less than 50 lines |
||||
* Anonymous classes: less than 50 lines |
||||
* Inner classes: not much more than 50 lines |
||||
* Classes: a few hundred lines |
||||
- Be thoughtfully organised in terms of method order, package structure, and module usage |
||||
- Follow well-established patterns and conventions |
||||
- Be consistent |
||||
- Make it easy to follow the control flow by _clicking through_ in an IDE |
||||
- Make it easier to use the right way than the wrong way |
||||
- Avoid abbreviations. We are a global team and when English is a second language abbreviations reduce readability. The following abbreviations are exceptions: |
||||
* tx -> Transaction |
||||
* IBFT -> Istanbul Byzantine Fault Tolerant (a consensus protocol) |
||||
* EVM -> Ethereum Virtual Machine |
||||
* P2P -> Peer to Peer |
||||
* RPC -> Remote Procedure Call |
||||
|
||||
# 3.2 Creating Code for Constant Refactoring and Evolving Design |
||||
|
||||
So the code can cope with constant refactoring and evolving design, write code that: |
||||
* Is well tested. |
||||
|
||||
Avoid test cases requiring detailed interactions with mocks because these are often brittle. |
||||
|
||||
* Avoids duplication. |
||||
|
||||
* Follows the Single Responsibility Principle where each class is responsible for one thing. |
||||
|
||||
>**Note** It is important to scope the responsibility wisely. Responsibilities that are: |
||||
> * Too small lead to an explosion of classes making things hard to follow |
||||
> * Too large lead to the class becoming big and unwieldy |
||||
|
||||
* Favors composition over inheritance. You can use inheritance, but prefer composition |
||||
|
||||
* Uses dependency injection |
||||
- Constructors should be simple, with dependencies passed in rather than built in the constructor |
||||
- Besu does not use a dependency injection framework |
||||
|
||||
* Validates method parameters for public methods using the Guava `Preconditions` class. Avoid validating parameters in private methods |
||||
|
||||
* Generally avoids interfaces with a single implementation unless they are explicitly being used to narrow the exposed API |
||||
|
||||
* Uses the most general applicable type. For example, `List` or `Collection` instead of `ArrayList` |
||||
|
||||
## 3.3 Additional Design Elements |
||||
|
||||
|
||||
* Use Optional rather than returning null when not having a value is a normal case |
||||
|
||||
* Consider exception and error handling as part of the overall design. Besu avoids checked exceptions |
||||
|
||||
* Give threads meaningful names. For example: |
||||
`Executors.newFixedThreadPool(1, new ThreadFactoryBuilder().setNameFormat(“Ibft”).build())` |
||||
|
||||
|
||||
# 4 Java |
||||
|
||||
## 4.1 Style Guide |
||||
|
||||
Besu follows the [Google code style](https://google.github.io/styleguide/javaguide.html) and uses spotless to ensure consistency of formatting. |
||||
|
||||
To automatically reformat the code before creating a pull request, run: |
||||
|
||||
```json |
||||
./gradlew spotlessApply |
||||
``` |
||||
|
||||
### 4.1.1 Install Google Style Settings |
||||
|
||||
The Google style settings can be installed in [Intellij](https://github.com/google/google-java-format#intellij) and [Eclipse](https://github.com/google/google-java-format#eclipse). |
||||
|
||||
## 4.2 Additional Java Style Guidelines |
||||
|
||||
## 4.2.1 Fields |
||||
|
||||
Class-level fields are generally not separated by blank lines but can use a blank line to separate them into logical groupings. |
||||
|
||||
## 4.2.2 Final Keyword |
||||
|
||||
Method parameters must be final. Class level and local fields should be final whenever possible. |
||||
|
||||
## 4.2.3 Common Methods |
||||
|
||||
* Getters follow idiomatic format with `get` prefix. For example, `getBlock()` gets a block property. |
||||
* Setters follow idiomatic format with `set` prefix. For example, `setBlock(Block block)` sets a block property. |
||||
* The Setter pattern should not be used for chained builder methods. |
||||
* Methods returning a `Stream` should be prefixed with `stream`. For example `streamIdlePeers()` returns a stream of the idle peers. |
||||
* For `toString` methods use the Guava 18+ `MoreObjects.toStringHelper` |
||||
* Equals and `hashCode()` methods use the `Object.equals` and `Object.hash` methods (this is the _Java 7+_ template in IntelliJ. Don’t accept subclasses and don’t use getters) |
||||
|
||||
## 4.2.4 Testing |
||||
|
||||
* Don't use a fixed prefix (for example, `test`). Do explain the expected behaviour not just the situation |
||||
|
||||
Good: `returnTrueWhenValueIsXyz()` |
||||
|
||||
Bad: `valueIsXyz()` |
||||
|
||||
* Use AssertJ for assertions in preference to JUnit’s Assert class. |
||||
|
||||
To help future-proof the code (avoiding libraries that may be deprecated in the near future), avoid assertions from the `org.assertj.core.api.Java6Assertions` class. Java6 in the name is a concerning signal |
||||
|
||||
## 4.2.5 Miscellaneous |
||||
|
||||
* When creating loggers it should be the first declaration in the class with: |
||||
|
||||
`private static final Logger LOG = getLogger();` |
||||
|
||||
* Ternary operators are acceptable when they make the code clearer but should never be nested |
||||
|
||||
* Avoid TODO comments. Log a ticket instead |
||||
|
||||
* Specify Gradle dependency versions in `versions.gradle` |
||||
|
||||
* Don't use two or more blank lines in a row |
||||
|
||||
# 5 Logging |
||||
|
||||
Logging is important for understanding what Besu is doing at any given time (for example, progress while synchronizing) and investigating defects. During development, add logging to aid in these cases. |
||||
|
||||
## 5.1 Log Messages |
||||
|
||||
Make log messages: |
||||
* Not so frequent they are overwhelming in the log output |
||||
* At the appropriate level |
||||
* Detailed enough to understand what actually happened. For example: |
||||
|
||||
`Insufficient validators. Expected 10 but found 4` |
||||
|
||||
* As succinct as possible while still being clear. |
||||
|
||||
* Bad: `Insufficient validators. Expected 10 but got: [address, address, address, address, address, address]` |
||||
|
||||
## 5.2 Log Levels |
||||
|
||||
* _Trace_ |
||||
|
||||
Extremely detailed view showing the execution flow. Likely only useful to developers |
||||
|
||||
* _Debug_ |
||||
|
||||
Information that is diagnostically helpful to a wider group than just developers (for example, sysadmins) |
||||
|
||||
* _Info_ |
||||
|
||||
Generally useful information to log (for example, service start/stop, configuration assumptions). Default logging level |
||||
|
||||
* _Warn_ |
||||
|
||||
Anything that can potentially cause application oddities but from which Besu automatically recovers |
||||
|
||||
* _Error_ |
||||
|
||||
Any error which is fatal to the operation, but not Besu itself (for example, missing data) |
||||
|
||||
* _Fatal_ |
||||
|
||||
An error that forces a shutdown of Besu |
||||
@ -1,224 +1,31 @@ |
||||
# Contributing to Hyperledger Besu |
||||
:+1::tada: First off, thanks for taking the time to contribute! :tada::+1: |
||||
# Contributing to the Hyperledger Besu Documentation |
||||
## :tada: Thanks for taking the time to contribute! :tada: |
||||
|
||||
Welcome to the [Hyperledger Besu documentation] repository! The following is a set of guidelines for |
||||
contributing to this repo. |
||||
These are mostly guidelines, not rules. Use your best judgment, |
||||
and feel free to propose changes to this document in a pull request. |
||||
|
||||
## Table Of Contents |
||||
[Code of Conduct](#code-of-conduct) |
||||
|
||||
[I just have a quick question](#i-just-have-a-quick-question) |
||||
|
||||
[How To Contribute](#how-to-contribute) |
||||
* [Reporting Bugs](#reporting-bugs-in-the-doc) |
||||
* [Suggesting Enhancements](#suggesting-enhancements) |
||||
* [Your First Contribution](#your-first-contribution) |
||||
* [Pull Requests](#pull-requests) |
||||
* [Code Reviews] |
||||
|
||||
[Documentation Style Guide](#documentation-style-guide) |
||||
|
||||
[Pull Request Labels](#pull-request-labels) |
||||
|
||||
## Code of Conduct |
||||
|
||||
This project and everyone participating in it is governed by the |
||||
[Hyperledger code of conduct](https://wiki.hyperledger.org/display/HYP/Hyperledger+Code+of+Conduct). |
||||
By participating, you are expected to uphold this code. |
||||
Please report unacceptable behavior according to [Incident Procedure](https://wiki.hyperledger.org/display/HYP/Hyperledger+Code+of+Conduct#HyperledgerCodeofConduct-IncidentProcedure). |
||||
|
||||
## I just have a quick question |
||||
|
||||
> **Note:** Please don't file an issue to ask a question. You'll get faster results by using the resources below. |
||||
|
||||
* [Hyperledger Besu documentation] |
||||
* [Hyperledger Besu chat] |
||||
|
||||
## How To Contribute |
||||
### Reporting Bugs in the Doc |
||||
|
||||
This section guides you through submitting a documentation bug report. Following these guidelines helps maintainers |
||||
and the community understand your report, reproduce the behavior, and find related reports. |
||||
|
||||
Before creating documentation bug reports, please check the [before-submitting-a-bug-report](#before-submitting-a-bug-report) |
||||
checklist as you might find out that you don't need to create one. When you are creating a documentation bug report, |
||||
please [include as many details as possible](#how-do-i-submit-a-good-bug-report). |
||||
|
||||
> **Note:** If you find a **Closed** issue that seems like it is the same thing that you're experiencing, |
||||
open a new issue and include a link to the original issue in the body of your new one. |
||||
|
||||
#### Before Submitting A Bug Report |
||||
* **Confirm the problem** clear the cache of your browser and check if the issue is still there. You |
||||
can also disable all your browser plugins and see if the bug still happens. |
||||
* **Perform a [cursory search of project documentation issues](https://jira.hyperledger.org/browse/BESU-122?jql=project%20%3D%20BESU%20AND%20resolution%20%3D%20Unresolved%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC) |
||||
to see if the problem has already been reported. If it has **and the issue is still open**, add a comment |
||||
to the existing issue instead of opening a new one. |
||||
|
||||
#### How Do I Submit A (Good) Bug Report? |
||||
Bugs are tracked as [Jira issues](https://jira.hyperledger.org/browse/BESU-122?jql=project%20%3D%20BESU%20AND%20resolution%20%3D%20Unresolved%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC). |
||||
|
||||
Explain the problem and include additional details to help maintainers reproduce the problem: |
||||
|
||||
* **Use a clear and descriptive summary** for the issue to identify the problem. |
||||
* **Describe the exact steps which reproduce the problem** in as many details as possible. |
||||
* **Provide specific examples to demonstrate the steps**. Include links, search keywords which you |
||||
use in those examples. If you're providing snippets in the issue, use backticks (```) to format the |
||||
code snippets. |
||||
* **Describe the behavior you observed after following the steps** and point out what exactly is the |
||||
problem with that behavior. |
||||
* **Explain which behavior you expected to see instead and why.** |
||||
* **Include screenshots or screen recordings** which show you following the described steps and |
||||
clearly demonstrate the problem. |
||||
|
||||
Provide more context by answering these questions: |
||||
|
||||
* **Did the problem start happening recently** (e.g. after a doc update) or was this always a problem? |
||||
* If the problem started happening recently, **can you reproduce the problem in an older version of the doc?** |
||||
What's the most recent version in which the problem doesn't happen? |
||||
* **Can you reliably reproduce the issue?** If not, provide details about how often the problem happens |
||||
and under which conditions it normally happens. |
||||
|
||||
Include details about your configuration and environment: |
||||
|
||||
* **Which version of the doc are you browsing?** You can get the exact version by looking at the url. |
||||
* **What OS & Version are you running?** |
||||
* **What Browser & Version are you running?** |
||||
* **What Plugins/Extensions & Version have you installed and enabled in your browser?** |
||||
|
||||
### Suggesting Enhancements |
||||
|
||||
This section guides you through submitting an enhancement suggestion, including completely new features |
||||
and minor improvements to documentation. |
||||
|
||||
Following these guidelines helps maintainers and the community understand your suggestion and find related suggestions. |
||||
|
||||
Before creating enhancement suggestions, please check the |
||||
[before-submitting-an-enhancement-suggestion](#before-submitting-an-enhancement-suggestion) list as |
||||
you might find out that you don't need to create one. |
||||
|
||||
When you are creating an enhancement suggestion, please |
||||
[include as many details as possible](#how-do-i-submit-a-good-enhancement-suggestion). |
||||
|
||||
#### Before Submitting An Enhancement Suggestion |
||||
|
||||
* **Perform a [cursory search of project issues](https://jira.hyperledger.org/browse/BESU-122?jql=project%20%3D%20BESU%20AND%20resolution%20%3D%20Unresolved%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC)** |
||||
to see if the problem has already been reported. If it has **and the issue is still open**, add a comment |
||||
to the existing issue instead of opening a new one. |
||||
|
||||
#### How Do I Submit A (Good) Enhancement Suggestion? |
||||
|
||||
Enhancement suggestions are tracked as [Jira issues](https://pegasys1.atlassian.net/secure/Dashboard.jspa?selectPageId=10000). |
||||
Provide the following information: |
||||
|
||||
* **Use a clear and descriptive summary** for the issue to identify the problem. |
||||
* **Describe the exact steps which reproduce the problem** in as many details as possible. |
||||
* **Provide specific examples to demonstrate the steps**. Include links, search keywords which you |
||||
use in those examples. If you're providing snippets in the issue, use backticks (```) to format the |
||||
code snippets. |
||||
* **Describe the current behavior** and **explain which behavior you expected to see instead** and why. |
||||
* **Include screenshots or screen recordings** which help you demonstrate the steps where possible. |
||||
* **Explain why this enhancement would be useful** to most users. |
||||
* **Does this enhancement exist in other docs?** |
||||
* **Which version of the doc are you browsing?** You can get the exact version by looking at the url. |
||||
* **What OS & Version are you running?** |
||||
* **What Browser & Version are you running?** |
||||
* **What Plugins/Extensions & Version have you installed and enabled in your browser?** |
||||
|
||||
### Your First Contribution |
||||
Start by looking through the 'good first issue' and 'help wanted' labeled issues on the [Jira dashboard](https://jira.hyperledger.org/browse/BESU-122?jql=project%20%3D%20BESU%20AND%20resolution%20%3D%20Unresolved%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC): |
||||
* [Good First Issue][search-label-good-first-issue] - issues which should only require a few lines of code or documentation, |
||||
and a test or two. |
||||
* [Help wanted issues][search-label-help-wanted] - issues which are a bit more involved than `good first issue` issues. |
||||
|
||||
When you've identified an issue you'd like to work on, ping us on [Hyperledger Besu chat] and we'll assign it to you. |
||||
|
||||
### Contribution Workflow |
||||
The documentation is maintained using a "*contributor workflow*" where everyone without exception |
||||
contributes changes proposals using "*pull-requests*". |
||||
|
||||
This facilitates social contribution, easy testing, and peer review. |
||||
|
||||
To contribute changes, use the following workflow: |
||||
|
||||
1. [**Fork the repository**](https://github.com/hyperledger/besu-docs/fork). |
||||
1. **Clone your fork** to your computer. |
||||
1. **Create a topic branch** and name it appropriately. |
||||
Starting the branch name with the issue number is a good practice and a reminder to fix only one issue in a |
||||
Pull-Request (PR)._ |
||||
1. **Make your changes** adhering to the documentation conventions described below. |
||||
_In general a commit serves a single purpose and diffs should be easily comprehensible. |
||||
For this reason do not mix any formatting fixes or typo fixes with actual documentation changes._ |
||||
1. **Commit your changes** using a clear commit message. |
||||
1. **Test your changes** locally before pushing to ensure that what you are proposing is not breaking |
||||
another part of the doc. |
||||
* displaying the doc with [MkDocs] in a preview mode enables you to check the rendering as |
||||
explained in the [MkDocs And Markdown Guide](MKDOCS-MARKDOWN-GUIDE.md#preview-the-documentation). |
||||
1. **Push your changes** to your remote fork (usually labeled as `origin`). |
||||
1. **Create a pull-request** (PR) on the Besu doc repository. If the PR addresses an existing Jira issue, |
||||
include the issue number in the PR title in square brackets (for example, `[BESU-1234]`). |
||||
1. **Add labels** to identify the type of your PR. _For example, if your PR fixes a bug, add the "bug" label._ |
||||
1. If the PR address an existing Jira issue, comment in the Jira issue with the PR number. |
||||
1. **Ensure your changes are reviewed**. |
||||
_Select the reviewers you would like to review your PR. |
||||
If you don't know who to choose, simply select the reviewers proposed by GitHub or leave blank and |
||||
let us know on [Hyperledger Besu chat]._ |
||||
1. **Make any required changes** on your contribution from the reviewers feedback. |
||||
_Make the changes, commit to your branch, and push to your remote fork._ |
||||
1. **When your PR is validated**, all tests passed and your branch has no conflicts with the target branch, |
||||
you can **"squash and merge"** your PR and you're done. You contributed to [Hyperledger Besu documentation]! Thanks ! |
||||
|
||||
### Pull Requests |
||||
|
||||
The process described here has several goals: |
||||
|
||||
- Maintain documentation quality |
||||
- Fix problems that are important to users |
||||
- Engage the community in working toward the best possible documentation |
||||
- Enable a sustainable system for maintainers to review contributions |
||||
- Further explanation on PR & commit messages can be found in this post: |
||||
[How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/). |
||||
|
||||
Please follow these steps to have your contribution considered by the approvers: |
||||
|
||||
1. Ensure all commits have a Sign-off for DCO, as described in [DCO.md]. |
||||
2. Follow all instructions in [PULL-REQUEST-TEMPLATE.md](.github/pull_request_template.md). |
||||
4. Follow the [Style Guides](#documentation-style-guide). |
||||
5. After you submit your pull request, verify that all [status checks](https://help.github.com/articles/about-status-checks/) |
||||
are passing. |
||||
<details><summary>What if the status checks are failing?</summary>If a status check is failing, |
||||
and you believe that the failure is unrelated to your change, please leave a comment on the pull request |
||||
explaining why you believe the failure is unrelated. A maintainer will re-run the status check for you. |
||||
If we conclude that the failure was a false positive, then we will open an issue to track that problem |
||||
with our status check suite.</details> |
||||
Welcome to the **Hyperledger Besu documentation** repository! The following are links to a set of guidelines for contributing to this repo. |
||||
These are mostly guidelines, not rules. Use your best judgement, |
||||
and feel free to propose changes to this document in a pull request. |
||||
|
||||
While the prerequisites above must be satisfied prior to having your pull request reviewed, the reviewer(s) |
||||
may ask you to complete additional writing, or other changes before your pull request |
||||
can be ultimately accepted. Please refer to [Code Reviews]. |
||||
* [Hyperledger Besu documentation](http://besu.hyperledger.org/) |
||||
* [Hyperledger Besu Rocketchat](https://chat.hyperledger.org/channel/besu) |
||||
* [Hyperledger Besu Wiki](https://wiki.hyperledger.org/display/BESU/Hyperledger+Besu) |
||||
|
||||
## Documentation Style Guide |
||||
### Useful docs contributing links |
||||
|
||||
Doc style will be checked automatically during a build. |
||||
* [I just have a quick question](https://wiki.hyperledger.org/display/BESU/I+just+have+a+quick+question) |
||||
* [How to Contribute] |
||||
* [Reporting Bugs in the Doc](https://wiki.hyperledger.org/display/BESU/Reporting+Bugs+in+the+Doc) |
||||
* [Submitting a Documentation Enhancement Suggestion](https://wiki.hyperledger.org/display/BESU/Suggesting+Documentation+Enhancements) |
||||
* [Documentation Style Guide](https://wiki.hyperledger.org/display/BESU/Besu+Documentation+Style+Guide) |
||||
* [Pull Request Labels](https://wiki.hyperledger.org/display/BESU/Pull+Request+Labels) |
||||
|
||||
We have [documentation guidelines and examples](DOC-STYLE-GUIDE.md). |
||||
These rules are not automatically enforced but are recommended to make the documentation consistent |
||||
and enhance the user experience. |
||||
* [Security](SECURITY.md) |
||||
|
||||
Also have a look at our [MKDocs Markdown guide](MKDOCS-MARKDOWN-GUIDE.md) if you're not familiar with |
||||
MarkDown syntax. We also have a number of extensions that are available in the documentation described |
||||
in this guide. |
||||
|
||||
## Pull Request Labels |
||||
### Other important information |
||||
|
||||
| Label name | Description | |
||||
|-------------------------------------------------------------------------|--------------------------------------------------------------------------------------------| |
||||
| [`work-in-progress`][search-label-work-in-progress] | Pull requests which are still being worked on, more changes will follow. | |
||||
| [`requires-changes`][search-label-requires-changes] | Pull requests which need to be updated based on review comments and then reviewed again. | |
||||
| [`needs engineering approval`][search-label-needs-engineering-approval] | Pull requests which need to be approved from a technical person, mainly documentation PRs. | |
||||
* [Besu Roadmap](https://wiki.hyperledger.org/display/BESU/Roadmap) |
||||
* [Code of Conduct](https://wiki.hyperledger.org/display/BESU/Code+of+Conduct) |
||||
* [Governance](https://wiki.hyperledger.org/display/BESU/Governance) |
||||
|
||||
[Hyperledger Besu chat]: https://chat.hyperledger.org/channel/besu |
||||
[Hyperledger Besu documentation]: https://besu.hyperledger.org/ |
||||
[DCO.md]: ./DCO.md |
||||
[Code Reviews]: ./docs/community/code-reviews.md |
||||
[MkDocs]: https://www.mkdocs.org/ |
||||
[How to Contribute]: https://wiki.hyperledger.org/display/BESU/How+to+Contribute |
||||
|
||||
@ -1,110 +0,0 @@ |
||||
# Besu Documentation Style Guide |
||||
|
||||
## Purpose of this Document |
||||
|
||||
This document contains guidelines to ensure the Besu documentation is consistent and well organised. |
||||
|
||||
This is a living document and will evolve to better suit Besu users and contributors needs. |
||||
|
||||
> **Note:** Although not everything in this style guide is currently followed in the Besu |
||||
documentation, these guidelines are intended to be applied when writing new content and revising |
||||
existing content. |
||||
|
||||
**The primary audience for this document is:** |
||||
|
||||
* Members of the Besu team |
||||
* Developers and technical writers contributing to the Besu documentation |
||||
|
||||
## Mission Statement |
||||
|
||||
The Besu documentation contributes to a consistent and easy to understand experience for end users. |
||||
We're focused on creating a great experience for both new and expert users of Ethereum clients. |
||||
|
||||
## General Guidelines |
||||
|
||||
The guiding principles for the Besu documentation are: |
||||
1. Be consistent |
||||
1. Keep it simple but technically correct |
||||
1. Be proactive and suggest good practices |
||||
1. Be informative and exhaustive. |
||||
|
||||
### 1. Be Consistent |
||||
|
||||
Consistency is important to help our end users build a mental model of how Besu works. |
||||
By being consistent with our word choices, visual formatting, and style of communication it helps |
||||
users know what to expect when they refer to or search Besu documentation. |
||||
|
||||
### 2. Keep It Simple But Technically Correct |
||||
|
||||
Avoid technical jargon and always assume our end users may not be Ethereum experts. |
||||
|
||||
This doesn't mean explaining all Ethereum concepts in our documentation. Explain Besu functionality |
||||
and when an understanding of complex Ethereum concepts is required refer users to relevant resources. |
||||
|
||||
For example, to explain how the EVM works, link to ethdocs.org documentation such as |
||||
https://github.com/ethereum/wiki/wiki/Ethereum-Virtual-Machine-(EVM)-Awesome-List |
||||
|
||||
Simple explanations must still be technically correct. |
||||
|
||||
### 3. Be Proactive And Suggest Good Practices |
||||
|
||||
Being proactive means anticipating user needs and guiding them through a process. |
||||
This most often takes the form of notes or tip messages alongside the main explanation. |
||||
Put yourself in the user's shoes and consider what questions you would have when reading the documentation. |
||||
|
||||
Do not assume required steps are implied. Err on the side of including them if you are unsure. |
||||
|
||||
Documenting good practices is also important. |
||||
For example, instruct users to secure private keys and protect RPC endpoints a production environments. |
||||
|
||||
### 4. Be Informative But Concise |
||||
|
||||
We seek a balance between providing enough relevant information to help our users develop a solid |
||||
mental model of how Besu works without forcing them to read too much text or redundant detail. |
||||
|
||||
To provide additional detail, use sub-sections. |
||||
|
||||
## Writing Style Guide |
||||
|
||||
We use the [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/) as our general guide |
||||
to writing technical documentation. |
||||
We take guidance from it but do not apply every rule. |
||||
For example, we use title case rather than sentence case. |
||||
|
||||
The Micrsoft Style Guide aims for natural, simple, and clear communication. |
||||
|
||||
Here are some important points we follow: |
||||
|
||||
### Active Voice |
||||
Use active voice. Use _you_ to create a more personal friendly style. Avoid gendered pronouns (_he_ or _she_). |
||||
|
||||
### Contractions |
||||
Use contractions. For example, don’t. |
||||
|
||||
Use common contractions, such as it’s and you’re, to create a friendly, informal tone. |
||||
|
||||
### Recommend |
||||
It's acceptable to use "we recommend" to introduce a product recommendation. |
||||
Don't use "Hyperledger recommends" or "it is recommended." |
||||
|
||||
Example: Instead of _This is not recommended for production code_ use _We don't recommend this for production code_. |
||||
|
||||
### Directory vs Folder |
||||
Use _directory_ over _folder_ because we are writing for developers. |
||||
|
||||
### Title Case For Headings |
||||
Use title case for headings. |
||||
|
||||
Note: This is a case where we are not following the Microsoft Writing Style Guide. |
||||
|
||||
### Assumed Knowledge For Readers |
||||
We have two distinct audiences to consider when developing content: |
||||
|
||||
- New to Ethereum and Ethereum clients |
||||
- Experienced with Ethereum clients other than Besu. |
||||
|
||||
### Avoid Abbreviations |
||||
|
||||
Try not to use abbreviations [except for well known ones and some jargon](MKDOCS-MARKDOWN-GUIDE.md#abbreviations). |
||||
Don't use "e.g." but use "for example". |
||||
Don't use "i.e." but use "that is". |
||||
@ -1,425 +0,0 @@ |
||||
# MkDocs And Markdown Guide |
||||
|
||||
Hyperledger Besu documentation is written using [Markdown](https://daringfireball.net/projects/markdown/) syntax. |
||||
|
||||
However, we use two flavors of this syntax: |
||||
|
||||
- One for pages inside the [/docs] directory that will be rendered by [MkDocs] as described below |
||||
in the [Installed Markdown Extensions](#installed-markdown-extensions) section. |
||||
- Another using the [Github syntax](https://guides.github.com/features/mastering-markdown/) |
||||
for pages outside of this documentation directory. These are mainly files to support our [open source |
||||
community](https://github.com/hyperledger/besu-docs/community). |
||||
|
||||
## MkDocs Documentation Website |
||||
|
||||
The [Hyperledger Besu documentation website](https://besu.hyperledger.org/) is built from the content of the |
||||
[/docs] directory. |
||||
|
||||
### /docs Directory |
||||
|
||||
The [/docs] directory in the Hyperledger Besu documentation repository contains all the documentation that |
||||
is generated into a static HTML website using [MkDocs] and the [Mkdocs Material] theme and hosted by [readthedocs.org]. |
||||
|
||||
The documentation is automatically updated using [WebHooks](https://docs.readthedocs.io/en/stable/webhooks.html) |
||||
linking GitHub to the [readthedocs.org] site when you merge a pull-request in the master branch of |
||||
Hyperledger Besu documentation. |
||||
|
||||
The system also detects tags in the Github repository and takes care of making the latest stable release |
||||
and previous versions available. |
||||
|
||||
If any issues occur, contact the maintainers of the [Hyperledger Besu documentation project](https://readthedocs.org/projects/hyperledger-besu/). |
||||
|
||||
### MkDocs Configuration |
||||
|
||||
[MkDocs] is a Python tool that generates the static HTML website that is published. |
||||
|
||||
Our [MkDocs] setup uses a [Mkdocs Material] theme to render the html pages. It also comes with a number of useful extensions. |
||||
|
||||
[MkDocs] in configured in the [mdkocs.yml](./mkdocs.yml) file. |
||||
|
||||
This file configures: |
||||
|
||||
- Site meta data and variables |
||||
- Theme configuration |
||||
- Page navigation |
||||
- Extensions |
||||
- Plugins |
||||
|
||||
If you add pages to the documentation (rather than updating existing pages), update the "nav" section |
||||
to add your page and specify the page name. |
||||
|
||||
### Preview The Documentation |
||||
|
||||
We recommended previewing your work locally before pushing your changes within a pull-request. |
||||
As the final documentation is build with [MkDocs], you have to build your docs locally with this tool |
||||
to ensure the Markdown is correctly understood and displayed. |
||||
|
||||
To preview Hyperledger Besu documentation locally: |
||||
|
||||
- [Install Python 3](https://www.python.org/downloads/) |
||||
- Have PIP3 installed alongside Python 3. |
||||
- Install all the required dependencies : |
||||
```bash |
||||
pip3 install -r docs/requirements.txt |
||||
``` |
||||
- Run the following command in the project directory : |
||||
```bash |
||||
mkdocs serve |
||||
``` |
||||
- Follow the link displayed on the output of this command that |
||||
looks like `[I 190206 18:48:47 server:298] Serving on http://127.0.0.1:8000`, |
||||
here connect to [http://127.0.0.1:8000] |
||||
|
||||
You can let this doc server run while you work on the doc, it updates the local website |
||||
automatically when you save changes in your Markdown files. |
||||
|
||||
>**Important** |
||||
> |
||||
> Run `python --version` to make sure you are using version indicated in [readthedocs.yml](readthedocs.yml) file. |
||||
> |
||||
> If you are updating from a previous Python version you will also have to run pip3 install again and |
||||
check your path. |
||||
|
||||
## Formatting Markdown For Doc Site |
||||
|
||||
Final documentation rendering is essential, but the format of the Markdown files is also very important. |
||||
|
||||
Formatting the Markdown code helps reviewers and writers easily navigate in the code and review your changes. |
||||
|
||||
A few basic rules: |
||||
|
||||
- Each file must contain a header composed of [meta-data](https://squidfunk.github.io/mkdocs-material/extensions/metadata/) |
||||
and ended by a specific comment. |
||||
Ex: |
||||
```markdown |
||||
title: Installation overview |
||||
description: Overview and requirements to install Hyperledger Besu |
||||
<!--- END of page meta data --> |
||||
``` |
||||
- [As for other code](https://google.github.io/styleguide/javaguide.html#s4.4-column-limit), |
||||
each line of Markdown code must be limited to 100 columns long to be readable on any editor. |
||||
Lines have to be wrapped without cutting the line in the middle of a word. A line break displays as a space. |
||||
- No HTML markup can be used inside a Markdown document. |
||||
We provide [a lot of extensions](#installed-markdown-extensions) that are able to do the same thing |
||||
without HTML. If you think one is missing, just discuss it with the team on [Besu chat] and we'll decide together |
||||
if it's worth adding an extension. |
||||
- Only one first level title can be present on a page. |
||||
- Format tables so they are also readable in the source code. |
||||
You can quickly achieve this by using a tool like http://markdowntable.com/ |
||||
|
||||
## Installed Markdown Extensions |
||||
|
||||
>**Important** |
||||
> Extensions are only available for the docs under [/docs] directory. |
||||
|
||||
As markdown can be a bit limited when it comes to some specific rendering of code, TOCs, and other documentation |
||||
elements, we configured some extensions for these items. |
||||
Extensions enable you to use simple Markdown syntax to achieve some complex rendering. |
||||
|
||||
>**Important** |
||||
> Never use HTML tags directly in the Markdown files to try to render content. |
||||
For consistency reasons we only allow the specific renderings available in the extensions. |
||||
|
||||
Here is a list of the available extensions: |
||||
|
||||
### TOC |
||||
|
||||
This extension automatically displays a table of content of the current page on the right side of the page. |
||||
It displays titles to the third level (`###`). After the third level, titles won't be displayed in the TOC. |
||||
|
||||
This extension also displays a link on the right of any title called "permalink". |
||||
This link can be used to point directly to the title from another website. |
||||
|
||||
### Include |
||||
|
||||
If you have content to be repeated on multiple pages, you can create it in a common page in and include |
||||
it in all required pages. |
||||
|
||||
Example: |
||||
To include the content of the "test_accounts.md" page in the "[/docs/global](./docs/global)" directory in another page, use: |
||||
```markdown |
||||
{!global/test_accounts.md!} |
||||
``` |
||||
|
||||
>**Important** |
||||
> An [exclude plugin](https://github.com/apenwarr/mkdocs-exclude) is installed |
||||
> (see [mkdocs.yml](mkdocs.yml) file for the config of exclusions). |
||||
> It excludes pages from the final rendered site as otherwise every .md file is rendered and copied. |
||||
> Pages will still be in the source repository but they won't be copied in the final site and won't |
||||
> appear in the search results even if you did not link them from the navigation. It's handy to |
||||
> prevent include files to be reachable as standalone pages as they are intended to be included in |
||||
> other pages. |
||||
|
||||
### Admonition |
||||
|
||||
The [Admonition extension](https://squidfunk.github.io/mkdocs-material/extensions/admonition/#admonition) |
||||
enables information, warning, and danger blocks. |
||||
|
||||
Example: |
||||
````markdown |
||||
!!! note |
||||
This is a multi line note |
||||
in the Hyperledger Besu documentation. |
||||
```` |
||||
|
||||
The 4 spaces indentation is required for the content to be part of the admonition. |
||||
|
||||
We generally use the following [types](https://squidfunk.github.io/mkdocs-material/extensions/admonition/#types) |
||||
in our documentation: |
||||
|
||||
- **Note** : Used to add information about a subject that doesn't directly needs to be taken in account |
||||
to use this specific part. |
||||
Example: "Available since v0.8.3" |
||||
- **Abstract** : Used at the beginning of a long article. Also known as "TL;DR", this can help users jump |
||||
into the content knowing that they will find their answer somewhere in the page. |
||||
- **Info** : Used to provide detail about a specific part of the documentation. |
||||
Ex: "The miner coinbase account is one of the accounts defined in the genesis file." |
||||
- **Tip** : Used to provide information that could help improve the use of the tool, make it faster. |
||||
Example: "To restart the private network in the future, start from 4. Restart First Node as Bootnode." |
||||
- **Warning** : Used to warn the users about something important. |
||||
Ex: "This will be deprecated in next version." |
||||
- **Danger** : Used to alert the user about a potential dangerous effect such as a risk of destroying |
||||
something or losing assets. |
||||
Ex: "Never use the development private keys for production use". |
||||
- **Example** : used to display an example. We usually use it with a single or tabbed code-block: |
||||
````markdown |
||||
!!! example |
||||
This example shows how to use the `net_listening` RPC method. |
||||
|
||||
```bash tab="curl HTTP request" |
||||
$ curl -X POST --data '{"jsonrpc":"2.0","method":"net_listening","params":[],"id":53}' <JSON-RPC-http-endpoint:port> |
||||
``` |
||||
|
||||
```bash tab="wscat WS request" |
||||
{"jsonrpc":"2.0","method":"net_listening","params":[],"id":53} |
||||
``` |
||||
|
||||
```json tab="JSON result" |
||||
{ |
||||
"jsonrpc" : "2.0", |
||||
"id" : 53, |
||||
"result" : true |
||||
} |
||||
``` |
||||
```` |
||||
|
||||
### Footnotes |
||||
|
||||
The [Footnotes extension](https://squidfunk.github.io/mkdocs-material/extensions/footnotes/) enables |
||||
adding footnotes. |
||||
|
||||
Footnotes display content at the end of the page and a numbered link inside the text to go to this content. |
||||
The extension also adds a link at the end of the footnote back to the text. |
||||
|
||||
### Definitions List |
||||
|
||||
The [def_list extension](https://python-markdown.github.io/extensions/definition_lists/) enables listing definitions |
||||
directly in the Markdown. |
||||
|
||||
### Abbreviations |
||||
|
||||
Generally we avoid the use of abbreviations but some like "PoW" for proof-of-work or "dApp" for |
||||
decentralized application are now part of the Ethereum jargon. The [Abbreviation extension](https://python-markdown.github.io/extensions/abbreviations/) |
||||
enables a tool tip hint to be provided for abbreviations. |
||||
|
||||
Place abbreviations at the beginning of the Markdown file just after the meta-data header. |
||||
|
||||
Example: |
||||
```markdown |
||||
description: This is an example page |
||||
<!--- END of page meta data --> |
||||
|
||||
*[PoA]: Proof of Work |
||||
|
||||
Clique is a PoA mechanism used in the Rinkeby test network |
||||
``` |
||||
|
||||
### Math |
||||
|
||||
[Arithmatex extension](https://squidfunk.github.io/mkdocs-material/extensions/pymdown/#arithmatex-mathjax ) |
||||
enables writing math formulas in the documentation using the provided syntax. |
||||
|
||||
Example: |
||||
```markdown |
||||
$\sigma=\displaystyle\prod_{k=1}^t\sigma_{i_k}^{L_{i_k}(0)}$ |
||||
|
||||
Constructing the threshold signature $\sigma$ from $t$ individual |
||||
signatures $\sigma_{i_k}$, $k=1,\dots,t$ and the Lagrange polynomials |
||||
$L_{i_1}, \dots,L_{i_t}$ associated to the set $I=\{i_1,\dots,i_t\}$ of signers. |
||||
``` |
||||
|
||||
### Better Emphasis |
||||
|
||||
The [Betterem extension](https://facelessuser.github.io/pymdown-extensions/extensions/betterem/) is |
||||
automatically applied to your bold and italic content. |
||||
|
||||
### Keyboard Shortcuts |
||||
|
||||
The [Keys syntax](https://facelessuser.github.io/pymdown-extensions/extensions/keys/) extension enables |
||||
displaying keyboard shortcuts. |
||||
|
||||
Example: |
||||
```markdown |
||||
++ctrl+C++ |
||||
``` |
||||
|
||||
### Folding Details Blocks |
||||
|
||||
You can use a folding block to hide content. The block can be closed by default or open. |
||||
This pattern helps reduce the content length and enables a faster overview of the whole page. |
||||
|
||||
Ex: |
||||
```markdown |
||||
???+ note "Folding details" |
||||
This is the detail of my content. |
||||
The plus sign makes it unfolded by default. |
||||
Remove the plus sign and it will be folded by default. |
||||
``` |
||||
|
||||
### Emojis |
||||
|
||||
Emojis are fun, but they can also be useful to draw the reader's attention. |
||||
Try to use only neutral emojis like :warning: |
||||
|
||||
Refer to a [supported full list of available emojis](https://www.webfx.com/tools/emoji-cheat-sheet/) |
||||
to find the suitable code. |
||||
|
||||
Example: |
||||
`:warning:` displays :warning: |
||||
|
||||
### Magic Links |
||||
|
||||
If you want an URL to be displayed as a link, simply write it and this extension automatically displays it as |
||||
a link. You don't need to surround it with Markdown links syntax. |
||||
|
||||
### Highlight Content |
||||
|
||||
The [Mark extension](https://facelessuser.github.io/pymdown-extensions/extensions/mark/) enables highlighting of |
||||
content. |
||||
|
||||
Text surrounded by double equals is highlighted in yellow. |
||||
|
||||
Example: |
||||
```markdown |
||||
==This is highlighted text== |
||||
``` |
||||
|
||||
### Strike Through |
||||
|
||||
The [tilde syntax](https://squidfunk.github.io/mkdocs-material/extensions/pymdown/#tilde) extensions enables text |
||||
strike through to be displayed. |
||||
|
||||
Example: |
||||
```markdown |
||||
~~This is the wrong way to do~~ |
||||
``` |
||||
|
||||
### Symbols |
||||
|
||||
The [Smart symbols syntax](https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/) enables |
||||
the inclusion of symbols. |
||||
|
||||
Ex: |
||||
`-->` will draw a nice right arrow. |
||||
|
||||
### Task lists |
||||
|
||||
The [Task list syntax](https://squidfunk.github.io/mkdocs-material/extensions/pymdown/#tasklist) extension |
||||
enables displaying a list as a checklist. |
||||
|
||||
### Code Samples And Examples With [SuperFences] |
||||
|
||||
#### Format The Code |
||||
|
||||
For writing code examples inside the documentation, refer to the developer style guides: |
||||
|
||||
- Java : refer to Hyperledger Besu [coding convention](https://github.com/hyperledger/besu/blob/master/CODING-CONVENTIONS.md). |
||||
- JSON : use https://jsonformatter.curiousconcept.com/ to format your JSON code. |
||||
- TOML : we follow version 0.5.0 language definition. |
||||
- JavaScript : see [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html). |
||||
|
||||
#### Including Code in the Documentation |
||||
|
||||
We use code-blocks provided by the [SuperFences] extension to present code samples and examples in the |
||||
documentation. |
||||
|
||||
A basic code-block uses triple back ticks and the language name to enable syntax highlighting. |
||||
|
||||
For example, a JSON result is written as: |
||||
|
||||
````markdown |
||||
```json |
||||
{ |
||||
"jsonrpc": "2.0", |
||||
"id": 1, |
||||
"result": true |
||||
} |
||||
``` |
||||
```` |
||||
|
||||
#### Tabbed Code Blocks |
||||
|
||||
[SuperFences] enables additional functionality such as the tabbed code-block. |
||||
|
||||
For example, to group the usage syntax and a usage example in the same block with tabs: |
||||
|
||||
````markdown |
||||
```bash tab="Syntax" |
||||
$ besu rlp encode [--from=<FILE>] [--to=<FILE>] [--type=<type>] |
||||
``` |
||||
|
||||
```bash tab="File Example" |
||||
$ besu rlp encode --from=ibft_extra_data.json --to=extra_data_for_ibft_genesis.txt --type=IBFT_EXTRA_DATA |
||||
``` |
||||
|
||||
```bash tab="Standard Input/Output Example" |
||||
$ cat extra_data.json | besu rlp encode > rlp.txt |
||||
``` |
||||
|
||||
#### Line Numbers On Long Code Samples |
||||
|
||||
[SuperFences] can also add [line numbers](https://facelessuser.github.io/pymdown-extensions/extensions/superfences/#showing-line-numbers) |
||||
to the code sample which makes it easier when discussing the code the sample. |
||||
|
||||
The line numbers will only appear on the code block that uses the `linenums="1"` parameter. |
||||
|
||||
Example: |
||||
````markdown |
||||
```javascript linenums="1" |
||||
// A very long javascript sample code |
||||
``` |
||||
```` |
||||
|
||||
#### Code Syntax Highlight |
||||
|
||||
Codehilite extension enables automatic syntax highlighting of code blocks. Define the language after |
||||
the code block delimiter to ensure correct highlighting. |
||||
If you don't provide the language name, the extension attempts to automatically discover it |
||||
but this can lead to errors. |
||||
|
||||
Example: |
||||
````markdown |
||||
```json |
||||
{ |
||||
"jsonrpc" : "2.0", |
||||
"id" : 51, |
||||
"result" : { |
||||
"startingBlock" : "0x5a0", |
||||
"currentBlock" : "0xad9", |
||||
"highestBlock" : "0xad9" |
||||
} |
||||
} |
||||
``` |
||||
```` |
||||
|
||||
|
||||
Pygment is the implementation for this extension, refer to [Pygment website](https://pygments.org/) for a |
||||
list of the supported languages. |
||||
|
||||
|
||||
[/docs]: ./docs |
||||
[MkDocs]: https://www.mkdocs.org/ |
||||
[readthedocs.org]: https://readthedocs.org/ |
||||
[Mkdocs Material]: https://squidfunk.github.io/mkdocs-material/ |
||||
[Besu chat]: https://chat.hyperledger.org/channel/besu |
||||
[SuperFences]: https://squidfunk.github.io/mkdocs-material/extensions/pymdown/#superfences |
||||
@ -1,26 +0,0 @@ |
||||
# Code review guidelines for Besu developers |
||||
|
||||
All changes must be code reviewed. For non-approvers this is obvious, since |
||||
you can't commit anyway. But even for approvers, we want all changes to get at |
||||
least one review, preferably (for non-trivial changes obligatorily) from someone |
||||
who knows the areas the change touches. For non-trivial changes we may want two |
||||
reviewers. The primary reviewer will make this decision and nominate a second |
||||
reviewer, if needed. Except for trivial changes, PRs should not be committed |
||||
until relevant parties (e.g. owners of the subsystem affected by the PR) have |
||||
had a reasonable chance to look at PR in their local business hours. |
||||
|
||||
Most PRs will find reviewers organically. If an approver intends to be the |
||||
primary reviewer of a PR they should set themselves as the assignee on GitHub |
||||
and say so in a reply to the PR. Only the primary approver of a change should |
||||
actually do the merge, except in rare cases (e.g. they are unavailable in a |
||||
reasonable timeframe). |
||||
|
||||
If a PR has gone 2 work days without an approver emerging, please ask on [Besu chat] |
||||
|
||||
## Attribution |
||||
|
||||
This Document was adapted by the following: |
||||
- Kubernetes collab.md, available at [kub collab] |
||||
|
||||
[kub collab]: https://raw.githubusercontent.com/kubernetes/community/master/contributors/guide/collab.md |
||||
[Besu chat]: https://chat.hyperledger.org/channel/besu |
||||
@ -1,81 +0,0 @@ |
||||
# Checkout code and build it |
||||
|
||||
## Prerequisites |
||||
|
||||
* Java 11+ |
||||
|
||||
## Quick start |
||||
|
||||
```sh |
||||
git clone --recursive https://github.com/hyperledger/besu |
||||
cd besu |
||||
./gradlew build |
||||
./gradlew integrationTest |
||||
``` |
||||
|
||||
## Checkout source code |
||||
|
||||
``` |
||||
git clone --recursive git@github.com:hyperledger/besu.git |
||||
``` |
||||
OR |
||||
``` |
||||
git clone --recursive https://github.com/hyperledger/besu |
||||
``` |
||||
|
||||
## See what tasks are available |
||||
To see all of the gradle tasks that are available: |
||||
``` |
||||
cd besu |
||||
./gradlew tasks |
||||
``` |
||||
|
||||
|
||||
## Build from source |
||||
After you have checked out the code, this will build the distribution binaries. |
||||
``` |
||||
cd besu |
||||
./gradlew build |
||||
``` |
||||
|
||||
## Run tests |
||||
All the unit tests are run as part of the build, but can be explicitly triggered with: |
||||
``` |
||||
./gradlew test |
||||
``` |
||||
The integration tests can be triggered with: |
||||
``` |
||||
./gradlew integrationTest |
||||
``` |
||||
|
||||
The reference tests (described below) can be triggered with: |
||||
``` |
||||
./gradlew referenceTest |
||||
``` |
||||
The system tests can be triggered with: |
||||
``` |
||||
./gradlew smokeTest |
||||
``` |
||||
The acceptance tests can be triggered with: |
||||
``` |
||||
./gradlew acceptanceTest |
||||
``` |
||||
|
||||
### Ethereum reference tests |
||||
|
||||
On top of the project proper unit tests, specific unit tests are provided to |
||||
run the Ethereum reference tests available at https://github.com/ethereum/tests |
||||
and described at http://ethereum-tests.readthedocs.io/en/latest/. Those are run |
||||
as part of the unit test suite as described above, but for debugging, it is |
||||
often convenient to run only a subset of those tests, for which a few convenience |
||||
as provided. For instance, one can run only "Frontier" general state tests with |
||||
``` |
||||
./gradlew :ethereum:org.hyperledger.besu.ethereum.vm:referenceTest -Dtest.single=GeneralStateTest -Dtest.ethereum.state.eip=Frontier |
||||
``` |
||||
or only the tests that match a particular pattern with something like: |
||||
``` |
||||
gradle :ethereum:org.hyperledger.besu.ethereum.vm:test -Dtest.single=GeneralStateTest -Dtest.ethereum.include='^CALLCODE.*-Frontier' |
||||
``` |
||||
Please see the comment on the `test` target in the top level `build.gradle` |
||||
file for more details. |
||||
|
||||
@ -1,10 +0,0 @@ |
||||
# Code coverage |
||||
|
||||
We use the jacoco test coverage plugin, which will generate coverage data whenever tests are run. |
||||
|
||||
To run the report: |
||||
``` |
||||
./gradlew test jacocoTestReport jacocoRootReport |
||||
``` |
||||
|
||||
The report will be available at `build/reports/jacoco/test/html/index.html` |
||||
@ -1,21 +0,0 @@ |
||||
# Logging |
||||
|
||||
This project employs the logging utility [Apache Log4j](https://logging.apache.org/log4j/2.x/), |
||||
accordingly levels of detail can be specified as follows: |
||||
|
||||
``` |
||||
OFF: The highest possible rank and is intended to turn off logging. |
||||
FATAL: Designates very severe error events that will presumably lead the application to abort. |
||||
ERROR: Designates error events that might still allow the application to continue running. |
||||
WARN: Designates potentially harmful situations. |
||||
INFO: Designates informational messages that highlight the progress of the application at coarse-grained level. |
||||
DEBUG: Designates fine-grained informational events that are most useful to debug an application. |
||||
TRACE: Designates finer-grained informational events than the DEBUG. |
||||
ALL: All levels including custom levels. |
||||
``` |
||||
|
||||
One mechanism of globally effecting the log output of a running client is though modification the file |
||||
`/besu/src/main/resources/log4j2.xml`, where it can be specified under the `<Property name="root.log.level">`. |
||||
As such, corresponding instances of information logs throughout the codebase, e.g. `log.fatal("Fatal Message!");`, |
||||
will be rendered to the console while the client is in use. |
||||
|
||||
@ -1,17 +0,0 @@ |
||||
# Running Developer Builds |
||||
|
||||
Build and run Besu with default options using: |
||||
|
||||
``` |
||||
./gradlew installDist |
||||
``` |
||||
|
||||
By default this stores all persistent data in `build/install/besu`. |
||||
|
||||
To set custom CLI arguments for the Besu execution: |
||||
|
||||
```sh |
||||
cd build/install/besu |
||||
|
||||
./bin/besu --discovery-enabled=false --data-path=/tmp/besutmp |
||||
``` |
||||
|
Before Width: | Height: | Size: 13 KiB |
|
Before Width: | Height: | Size: 10 KiB |
|
Before Width: | Height: | Size: 9.9 KiB |
|
Before Width: | Height: | Size: 1.4 KiB |
|
Before Width: | Height: | Size: 21 KiB |
|
Before Width: | Height: | Size: 9.6 KiB |
|
Before Width: | Height: | Size: 23 KiB |
|
Before Width: | Height: | Size: 8.8 KiB |
|
Before Width: | Height: | Size: 11 KiB |
|
Before Width: | Height: | Size: 46 KiB |
|
Before Width: | Height: | Size: 13 KiB |
Loading…
Reference in new issue