mirror of https://github.com/hyperledger/besu
Refactor/contributor content (#321)
* Contributor Content: complete refactor - Deleted contributor files now hosted in wiki, (CLI-STYLE-GUIDE.md, CODE-OF-CONDUCT.md, CODING-CONVENTIONS.md, ROADMAP.md, SECURITY.md). - Deleted old docs files in /docs folder (except readme for redirect). - Refactored the root README.md with relevant content. - Refactored the CONTRIBUTING.md file to simplify it with links to wiki. * added contact developer advocate link * small updates on README and CONTRIBUTING MDs. * README updated. * unified links for docs, jira, etc * updated suggestions from PR comments * updated links from comments * updated links that still pointed to internal /docs * LF wording and links Signed-off-by: Felipe Faraggi <felipefaraggi@gmail.com> Co-authored-by: Nicolas MASSART <NicolasMassart@users.noreply.github.com>pull/348/head
Felipe Faraggi
5 years ago
committed by
GitHub
parent
76f1493b27
commit
2c1a0cc64d
@ -1,230 +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,74 +0,0 @@ |
||||
# Contributor Covenant Code of Conduct |
||||
|
||||
## Our Pledge |
||||
|
||||
In the interest of fostering an open and welcoming environment, we as |
||||
contributors and maintainers pledge to making participation in our project and |
||||
our community a harassment-free experience for everyone, regardless of age, body |
||||
size, disability, ethnicity, sex characteristics, gender identity and expression, |
||||
level of experience, education, socio-economic status, nationality, personal |
||||
appearance, race, religion, or sexual identity and orientation. |
||||
|
||||
## Our Standards |
||||
|
||||
Examples of behavior that contributes to creating a positive environment |
||||
include: |
||||
|
||||
* Using welcoming and inclusive language |
||||
* Being respectful of differing viewpoints and experiences |
||||
* Gracefully accepting constructive criticism |
||||
* Focusing on what is best for the community |
||||
* Showing empathy towards other community members |
||||
|
||||
Examples of unacceptable behavior by participants include: |
||||
|
||||
* The use of sexualized language or imagery and unwelcome sexual attention or |
||||
advances |
||||
* Trolling, insulting/derogatory comments, and personal or political attacks |
||||
* Public or private harassment |
||||
* Publishing others' private information, such as a physical or electronic |
||||
address, without explicit permission |
||||
* Other conduct which could reasonably be considered inappropriate in a |
||||
professional setting |
||||
|
||||
## Our Responsibilities |
||||
|
||||
Project maintainers are responsible for clarifying the standards of acceptable |
||||
behavior and are expected to take appropriate and fair corrective action in |
||||
response to any instances of unacceptable behavior. |
||||
|
||||
Project maintainers have the right and responsibility to remove, edit, or |
||||
reject comments, commits, code, wiki edits, issues, and other contributions |
||||
that are not aligned to this Code of Conduct, or to ban temporarily or |
||||
permanently any contributor for other behaviors that they deem inappropriate, |
||||
threatening, offensive, or harmful. |
||||
|
||||
## Scope |
||||
|
||||
This Code of Conduct applies both within project spaces and in public spaces |
||||
when an individual is representing the project or its community. Examples of |
||||
representing a project or community include using an official project e-mail |
||||
address, posting via an official social media account, or acting as an appointed |
||||
representative at an online or offline event. Representation of a project may be |
||||
further defined and clarified by project maintainers. |
||||
|
||||
## Enforcement |
||||
|
||||
Instances of abusive, harassing, or otherwise unacceptable behavior may be |
||||
reported by contacting the project team at [private@pegasys.tech]. All |
||||
complaints will be reviewed and investigated and will result in a response that |
||||
is deemed necessary and appropriate to the circumstances. The project team is |
||||
obligated to maintain confidentiality with regard to the reporter of an incident. |
||||
Further details of specific enforcement policies may be posted separately. |
||||
|
||||
Project maintainers who do not follow or enforce the Code of Conduct in good |
||||
faith may face temporary or permanent repercussions as determined by other |
||||
members of the project's leadership. |
||||
|
||||
## Attribution |
||||
|
||||
This Code of Conduct is adapted from the [Contributor Covenant], version 1.4, |
||||
available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html |
||||
|
||||
[Contributor Covenant]: https://www.contributor-covenant.org |
||||
[private@pegasys.tech]: mailto:private@pegasys.tech |
||||
@ -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, `Bytes` encapsulates byte data and methods operating on the byte data. `Bytes.isZero()` is an instance method instead of accepting a `Bytes` 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,277 +1,35 @@ |
||||
# Contributing to Besu |
||||
:+1::tada: First off, thanks for taking the time to contribute! :tada::+1: |
||||
# Contributing to Hyperledger Besu |
||||
## :tada: Thanks for taking the time to contribute! :tada: |
||||
|
||||
Welcome to the Besu repository! The following is a set of guidelines for contributing to this |
||||
repo and its packages. These are mostly guidelines, not rules. Use your best judgment, |
||||
and feel free to propose changes to this document in a pull request. |
||||
Welcome to the Besu repository! The following links are a set of guidelines for contributing to this repo and its packages. These are mostly guidelines, not rules. Use your best judgement, and feel free to propose changes to this document in a pull request. Contributions come in the form of code submissions, writing documentation, raising issues, helping others in chat, and any other actions that help develop Besu. |
||||
|
||||
#### Table Of Contents |
||||
[Code of Conduct](#code-of-conduct) |
||||
### LF / Jira Accounts |
||||
|
||||
[I just have a quick question](#i-just-have-a-quick-question) |
||||
Having the following accounts is necessary for contributing code/issues to Besu. |
||||
* If you want to contribute code, you can make a [Linux Foundation (LF) account] here. |
||||
* If you want to raise an issue, you can login to your [Atlassian account here](https://id.atlassian.com/). |
||||
* Our Rocket Chat also requires a [Linux Foundation (LF) account]. |
||||
|
||||
[How To Contribute](#how-to-contribute) |
||||
* [Reporting Bugs](#reporting-bugs) |
||||
* [Suggesting Enhancements](#suggesting-enhancements) |
||||
* [Your First Contribution](#your-first-contribution) |
||||
* [Pull Requests](#pull-requests) |
||||
* [Code Reviews](#code-review) |
||||
### Useful contributing links |
||||
|
||||
[Style Guides](#style-guides) |
||||
* [Java Style Guide](#java-code-style-guide) |
||||
* [Coding Conventions](#coding-conventions) |
||||
* [Git Commit Messages & Pull Request Messages](#git-commit-messages--pull-request-messages) |
||||
* [I just have a quick question](https://wiki.hyperledger.org/display/BESU/I+just+have+a+quick+question) |
||||
* [How to Contribute] |
||||
* [First contribution workflow](https://wiki.hyperledger.org/display/BESU/First+contribution?src=contextnavpagetreemode) |
||||
* [Did you find a bug?](https://wiki.hyperledger.org/display/BESU/Reporting+Bugs) |
||||
* [Issues](https://wiki.hyperledger.org/display/BESU/Issues) |
||||
* [DCO](https://wiki.hyperledger.org/display/BESU/DCO) |
||||
* [Suggesting Enhancements](https://wiki.hyperledger.org/display/BESU/Suggesting+Enhancements) |
||||
* [Pull Requests](https://wiki.hyperledger.org/display/BESU/Pull+Requests) |
||||
* [Code Reviews](https://wiki.hyperledger.org/display/BESU/Code+Reviews) |
||||
|
||||
[Pull Request Labels](#pull-request-labels) |
||||
|
||||
## Code of Conduct |
||||
* [Security contributions](https://wiki.hyperledger.org/display/BESU/Security) |
||||
|
||||
This project and everyone participating in it is governed by the [Besu Code of Conduct](CODE-OF-CONDUCT.md). |
||||
By participating, you are expected to uphold this code. Please report unacceptable behavior to [private@pegasys.tech]. |
||||
### Other important information |
||||
|
||||
The [Hyperledger Code of Conduct](https://wiki.hyperledger.org/community/hyperledger-project-code-of-conduct) |
||||
also applies to participants in this project. |
||||
* [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) |
||||
|
||||
## Governance |
||||
|
||||
Hyperledger Besu is managed under an open governance model as described in the [HyperLedger |
||||
charter](https://www.hyperledger.org/about/charter). Hyperledger Besu is lead by a set of [maintainers](MAINTAINERS.md). |
||||
|
||||
## 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. |
||||
|
||||
* [Besu documentation] |
||||
* [Rocketchat] |
||||
|
||||
## How To Contribute |
||||
### Reporting Bugs |
||||
|
||||
This section guides you through submitting a bug report. Following these guidelines helps maintainers |
||||
and the community understand your report, reproduce the behavior, and find related reports. |
||||
|
||||
Before creating 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 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** is reproducible in the latest version of the software |
||||
* **Check [Besu documentation]**. You might be able to find the cause of the problem and fix things yourself. |
||||
* **Perform a [cursory search of project issues](https://jira.hyperledger.org/projects/BESU/issues/BESU-122?filter=allopenissues)** |
||||
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. For example, |
||||
start by explaining how you started Besu, e.g. which command exactly you used in the terminal, |
||||
or how you started it otherwise. |
||||
* **Provide specific examples to demonstrate the steps**. Include links to files or GitHub projects, |
||||
or copy/pasteable snippets, 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** 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 updating to a new version of the software) |
||||
or was this always a problem? |
||||
* If the problem started happening recently, **can you reproduce the problem in an older version of the software?** |
||||
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 software are you using?** You can get the exact version by running `besu -v` in your terminal. |
||||
* **What OS & Version are you running?** |
||||
* **For Linux - What kernel are you running?** You can get the exact version by running `uname -a` in your terminal. |
||||
* **Are you running in a virtual machine?** If so, which VM software are you using and which operating |
||||
systems and versions are used for the host and the guest? |
||||
* **Are you running in a docker container?** If so, what version of docker? |
||||
* **Are you running in a a Cloud?** If so, which one, and what type/size of VM is it? |
||||
* **What version of Java are you running?** You can get the exact version by looking at the besu |
||||
logfile during startup. |
||||
|
||||
### Suggesting Enhancements |
||||
|
||||
This section guides you through submitting an enhancement suggestion, including completely new features |
||||
and minor improvements to existing functionality or documentation changes. |
||||
|
||||
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 |
||||
|
||||
* **Check the [Besu documentation].** You might be able to find the cause of the problem and fix things yourself. |
||||
* **Perform a [cursory search of project issues](https://pegasys1.atlassian.net/browse/PAN-2502?jql=project%20%3D%20PAN)** |
||||
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://jira.hyperledger.org/browse/BESU-122?jql=project%20%3D%20BESU%20AND%20resolution%20%3D%20Unresolved%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC). |
||||
Provide the following information: |
||||
|
||||
* **Use a clear and descriptive title** for the issue to identify the suggestion. |
||||
* **Provide a step-by-step description of the suggested enhancement** in as many details as possible. |
||||
* **Provide specific examples to demonstrate the steps**. If you're providing code 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** which help you demonstrate the steps where possible. |
||||
* **Explain why this enhancement would be useful** to most users. |
||||
* **Does this enhancement exist in other clients?** |
||||
* **Specify which version of the software you're using.** You can get the exact version by running |
||||
`besu -v` in your terminal. |
||||
* **Specify the name and version of the OS you're using.** |
||||
|
||||
## Your First Contribution |
||||
Start by looking through the 'good first issue' and 'help wanted' labeled issues on the [Jira dashboard](https://jira.hyperledger.org/projects/BESU/issues/BESU-122?filter=allopenissues): |
||||
* [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 [Rocketchat] and we'll assign it to you. |
||||
|
||||
### Contribution Workflow |
||||
The codebase and documentation are maintained using the same "*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/PegaSysEng/besu/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 coding 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 code moves with actual code changes._ |
||||
1. **Commit your changes** see [How to Write a Git Commit Message] article by [Chris Beams]. |
||||
1. **Test your changes** locally before pushing to ensure that what you are proposing is not breaking |
||||
another part of the software. Running the `./gradlew clean check test` command locally will help you |
||||
to be confident that your changes will pass CI tests once pushed as a Pull Request. |
||||
1. **Push your changes** to your remote fork (usually labeled as `origin`). |
||||
1. **Create a pull-request** (PR) on the Besu repository. If the PR addresses an existing Jira issue, |
||||
include the issue number in the PR title in square brackets (for example, `[BESU-2374]`). |
||||
1. **Add labels** to identify the type of your PR. _For example, if your PR is not ready to validate, |
||||
add the "work-in-progress" label. If it 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._ |
||||
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 Besu! Thanks ! |
||||
|
||||
### Architectural Best Practices |
||||
|
||||
Questions on architectural best practices will be guided by the principles set forth in |
||||
[Effective Java](http://index-of.es/Java/Effective%20Java.pdf) by Joshua Bloch |
||||
|
||||
### Automated Test coverage |
||||
All code submissions must be accompanied by appropriate automated tests. |
||||
The goal is to provide confidence in the code’s robustness, while avoiding redundant tests. |
||||
|
||||
### Pull Requests |
||||
|
||||
The process described here has several goals: |
||||
|
||||
- Maintain Product quality |
||||
- Fix problems that are important to users |
||||
- Engage the community in working toward the best possible product |
||||
- Enable a sustainable system for maintainers to review contributions |
||||
- Further explanation on PR & commit messages can be found in the |
||||
[How to Write a Git Commit Message] article by [Chris Beams]. |
||||
|
||||
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). |
||||
3. Include appropriate test coverage. Testing is 100% automated. All submissions must be testable in an automated fashion. |
||||
4. Follow the [Style Guides](#style-guides). |
||||
5. After you submit your pull request, verify that all [status checks](https://help.github.com/articles/about-status-checks/) |
||||
are passing. |
||||
|
||||
#### What Makes A Good Pull Request? |
||||
|
||||
The following guidelines, based on Hyperledger Fabic's [contribution guidelines](https://hyperledger-fabric.readthedocs.io/en/latest/CONTRIBUTING.html#what-makes-a-good-pull-request) will help ensure that your pull request gets promptly reviewed. |
||||
|
||||
##### One Pull Request, One Change |
||||
* This limits the surface area of the change, and makes it easier to identify root causes when issues arise. |
||||
|
||||
##### Link to JIRA |
||||
* When submitting your PR, include the JIRA ticket's link in the description and number in the title (i.e. `[BESU-99] My Awesome PR`), this helps provide more context on your work and auto-update the JIRA ticket to include a link to your PR. |
||||
|
||||
##### Minimize LOCs per PR |
||||
* PRs get near exponentially longer to review as the number of lines of code increase. Ideally, try and keep your changes to under 300 LOC. If that is not possible, try and break up your PR into smaller ones for reviewers to review sequentially. |
||||
* One way to do this if, for some reason, the change has to all go in the codebase at once, is to have a PR open on the Besu repository linking to smaller PRs on your Besu fork. |
||||
|
||||
##### Write Meaningful Commit Messages |
||||
* As mentioned above, your commit title should include the JIRA ticket number (i.e. `[BESU-99]`) while the description should link to the jira ticket. Please include a comprehensive description of the changes in your commit description. |
||||
|
||||
##### Be Responsive |
||||
* Don't let a PR sit idle with unaddressed comments until it gets to a point where you need to rebase the whole thing. If you are pausing your work on an issue, please indicate it in the PR comments. |
||||
|
||||
##### What if the status checks are failing? |
||||
* 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. |
||||
|
||||
## Code Review |
||||
While the prerequisites above must be satisfied prior to having your pull request reviewed, the reviewer(s) |
||||
may ask you to complete additional design work, tests, or other changes before your pull request |
||||
can be ultimately accepted. Please refer to [Code Reviews]. |
||||
|
||||
# Style Guides |
||||
|
||||
## Java Code Style Guide |
||||
|
||||
We use Google's Java coding conventions for the project. To reformat code, run: |
||||
|
||||
``` |
||||
./gradlew spotlessApply |
||||
``` |
||||
|
||||
Code style will be checked automatically during a build. |
||||
|
||||
## Coding Conventions |
||||
We have a set of [coding conventions](CODING-CONVENTIONS.md) to which we try to adhere. |
||||
These are not strictly enforced during the build, but should be adhered to and called out in code reviews. |
||||
|
||||
# Pull Request Labels |
||||
|
||||
#### Pull Request Labels |
||||
|
||||
| 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. | |
||||
|
||||
[private@pegasys.tech]: mailto:private@pegasys.tech |
||||
[Rocketchat]: https://chat.hyperledger.org/channel/besu |
||||
[Besu documentation]: https://besu.hyperledger.org/ |
||||
[DCO.md]: ./DCO.md |
||||
[Code Reviews]: /docs/community/code-reviews.md |
||||
[MkDocs]: https://www.mkdocs.org/ |
||||
[How to Write a Git Commit Message]: https://chris.beams.io/posts/git-commit/ |
||||
[Chris Beams]: https://github.com/cbeams |
||||
[How to Contribute]: https://wiki.hyperledger.org/display/BESU/How+to+Contribute |
||||
[Linux Foundation (LF) account]: https://identity.linuxfoundation.org/ |
||||
|
||||
@ -1,66 +0,0 @@ |
||||
# Roadmap |
||||
This document represents the current working roadmap for Besu. It is a living document, which will |
||||
evolve and change over time. In particular the features in later versions are likely to be refined and change. |
||||
|
||||
We use the approach of `#now`, `#next`, `#later` [used by foursquare](https://medium.com/@noah_weiss/now-next-later-roadmaps-without-the-drudgery-1cfe65656645), with a slightly different time horizon. |
||||
Our `#now` scale is about 3 months, `#next` about 6 months, and `+later` is 12+ months. |
||||
|
||||
## Now (up to v1.3) |
||||
Our key areas for now are: |
||||
* Making Besu a First Class Client |
||||
* Istanbul Support |
||||
* State Pruning |
||||
* Disaster recovery |
||||
|
||||
### Making Besu a First Class Client |
||||
|
||||
First and foremost, we want Besu to be a first class client for usage on both mainnet and permissioned networks. |
||||
This entails maintaining compatibility with mainnet, providing permissioning features and constantly improving Besu's performance. |
||||
Some recent additions to the client have been [UPnP Support](https://docs.besu.pegasys.tech/en/latest/Configuring-Besu/Networking/Using-UPnP/) |
||||
and a [GraphQL interface](https://docs.besu.pegasys.tech/en/latest/Besu-API/GraphQL/). |
||||
|
||||
### Istanbul Support |
||||
|
||||
Besu will support the upcoming Istanbul network upgrade and implement all required EIPs as per the [Hardfork Meta: Istanbul EIP](https://eips.ethereum.org/EIPS/eip-1679). |
||||
|
||||
### State Pruning |
||||
|
||||
State pruning will be implemented. State pruning reduces the disk space required for the Besu database by discarding outdated world state data. |
||||
|
||||
### Disaster Recovery |
||||
|
||||
Support key-value storage in relational databases to solidify a robust Disaster Recovery process. Note: Orion to support Oracle and Postgres in 1.3. |
||||
|
||||
## Next (v1.4) |
||||
The key areas for next are: |
||||
* Tracing APIs |
||||
* Enhancing key management capabilities |
||||
* Migration tools |
||||
* Ethereum 1.x |
||||
|
||||
### Tracing APIs |
||||
|
||||
Additional tracing APIs to be added. |
||||
|
||||
### Enhancing Key Management |
||||
|
||||
Enhancing key management capabilities by supporting secure storage of keys. |
||||
|
||||
### Migration Tools |
||||
|
||||
Adding tools to enable migration across consensus algorithms. |
||||
|
||||
### Ethereum 1.x |
||||
|
||||
The Besu team will help spearhead the Ethereum 1.x initiative by contributing to EIPs, community discussions, roadmap specificaton and eventually implementing the resulting features from the initiative. More information on the 1.x initiative can be found [here](https://docs.ethhub.io/ethereum-roadmap/ethereum-1.x/). |
||||
|
||||
## Future (v1.5+) |
||||
In addition to making incremental improvements to the above features, there will be some bigger pieces of work. |
||||
These are deliberately kept vague at this time, and will be elaborated upon when they move up to the now and next levels of work. |
||||
|
||||
* Ethereum 2.0 |
||||
* Alternate Consensus Mechanisms |
||||
* Sidechains |
||||
* Privacy group consensus |
||||
* Cross privacy group communication |
||||
* On-chain privacy |
||||
@ -1,23 +0,0 @@ |
||||
# Hyperledger Security Policy |
||||
|
||||
## Reporting a Security Bug |
||||
|
||||
If you think you have discovered a security issue in any of the Hyperledger |
||||
projects, we'd love to hear from you. We will take all security bugs |
||||
seriously and if confirmed upon investigation we will patch it within a |
||||
reasonable amount of time and release a public security bulletin discussing |
||||
the impact and credit the discoverer. |
||||
|
||||
There are two ways to report a security bug. The easiest is to email a |
||||
description of the flaw and any related information (e.g. reproduction |
||||
steps, version) to |
||||
[security at hyperledger dot org](mailto:security@hyperledger.org). |
||||
|
||||
The other way is to file a confidential security bug in our |
||||
[JIRA bug tracking system](https://jira.hyperledger.org). |
||||
Be sure to set the “Security Level” to “Security issue”. |
||||
|
||||
The process by which the Hyperledger Security Team handles security bugs |
||||
is documented further in our |
||||
[Defect Response](https://wiki.hyperledger.org/display/HYP/Defect+Response) |
||||
page on our [wiki](https://wiki.hyperledger.org). |
||||
@ -1,27 +0,0 @@ |
||||
description: Code review guidelines for Besu developers |
||||
<!--- END of page meta data --> |
||||
|
||||
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 Rocketchat] |
||||
|
||||
## 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/devel/collab.md |
||||
[Besu Rocketchat]: https://chat.hyperledger.org/channel/besu |
||||
@ -1,175 +0,0 @@ |
||||
description: Community organisation and members responsibilities |
||||
<!--- END of page meta data --> |
||||
|
||||
!!!note |
||||
This document is in progress |
||||
|
||||
This doc outlines the various responsibilities of contributor roles in |
||||
this project. |
||||
|
||||
| Role | Responsibilities | Defined by | |
||||
| -----| ---------------- | ---------- | |
||||
| Everyone | none | anybody with a belly button |
||||
| Member | everyone who contributes - code or otherwise | Besu GitHub org member |
||||
| Approver | approve accepting contributions | write permissions on master |
||||
| Project Manager | management of the project | Hyperledger |
||||
| Project Sponsor | contribute developer resources | Hyperledger |
||||
| Open Source Circle | OSS support | Hyperledger |
||||
| Project Evangelist | promote the project | Hyperledger |
||||
| Benevolent Dictator | decision tie-breaker | Hyperledger |
||||
|
||||
## Everyone |
||||
Any person from the public is able to access the code. The standard permissions grant the ability to view the code, view open bugs, access the wiki, download binaries, view CI results and comment on pull requests. |
||||
|
||||
## New contributors |
||||
|
||||
[New contributors] should be welcomed to the community by existing members, |
||||
helped with PR workflow, and directed to relevant documentation and |
||||
communication channels. |
||||
|
||||
## Established community members |
||||
|
||||
Established community members are expected to demonstrate their adherence to the |
||||
principles in this document, familiarity with project organization, roles, |
||||
policies, procedures, conventions, etc., and technical and/or writing ability. |
||||
Role-specific expectations, responsibilities, and requirements are enumerated |
||||
below. |
||||
|
||||
## Member |
||||
|
||||
Members are continuously active contributors in the community. They can have |
||||
issues and PRs assigned to them. |
||||
|
||||
### Requirements |
||||
|
||||
- Enabled [two-factor authentication] on their GitHub account |
||||
- Have made multiple contributions to the project or community. Contribution may include, but is not limited to: |
||||
- Authoring or reviewing PRs on GitHub |
||||
- Filing or commenting on issues on GitHub |
||||
- Contributing to community discussions (e.g. meetings, Slack, email discussion forums, Stack Overflow) |
||||
- Subscribed to [besu-dev@pegasys.tech] |
||||
- Joined [Besu Rocketchat] |
||||
- Browsed [Besu Wiki] |
||||
- Have read the [contributor guide] |
||||
- Signed ICLA, as described in [CLA.md] |
||||
|
||||
### Responsibilities and privileges |
||||
|
||||
- Responsive to issues and PRs assigned to them |
||||
- Active owner of code they have contributed (unless ownership is explicitly transferred) |
||||
- Code is well tested |
||||
- Tests consistently pass |
||||
- Addresses bugs or issues discovered after code is accepted |
||||
- Members can do `/lgtm` on open PRs |
||||
- They can be assigned to issues and PRs, and people can ask members for reviews with a `/cc @username` |
||||
|
||||
## Approver |
||||
|
||||
Code approvers are members that have signed an ICLA and have been granted additional commit privileges. While members are expected to provided code reviews that focus on code quality and correctness, approval is focused on holistic acceptance of a contribution including: backwards / forwards compatibility, adhering to API and flag conventions, subtle performance and correctness issues, interactions with other parts of the system, etc. |
||||
|
||||
**Defined by:** write permissions on master branch |
||||
|
||||
### Requirements |
||||
|
||||
- Includes all of the requirements of a Member user |
||||
- Signed ICLA, as described in [CLA.md] |
||||
- Approver status granted by Project Sponsor or the Open Source Circle |
||||
|
||||
### Responsibilities and privileges |
||||
- Includes all of the responsibilities and privileges of a Member user |
||||
- Approver status may be a precondition to accepting large code contributions |
||||
- Demonstrate sound technical judgement |
||||
- Responsible for project quality control via [code reviews] |
||||
- Focus on holistic acceptance of contribution such as dependencies with other features, backwards / forwards |
||||
compatibility, API and flag definitions, etc |
||||
- Expected to be responsive to review requests as per [community expectations] |
||||
- Mentor members |
||||
- May approve pull requests |
||||
- May merge pull requests |
||||
|
||||
## Project Manager |
||||
The Project Manager role provides the user with control over management aspects of the project. |
||||
|
||||
**Defined by:** Hyperledger |
||||
|
||||
### Requirements |
||||
- Includes all of the requirements of a Member user |
||||
- Signed ICLA, as described in [CLA.md] |
||||
- PM status granted by Project Sponsor or the Open Source Circle |
||||
|
||||
### Responsibilities and privileges |
||||
- Includes all of the responsibilities and privileges of a Member user |
||||
- Determining releases |
||||
- Managing roadmaps and access to Circle reports |
||||
|
||||
|
||||
|
||||
## Project Sponsor |
||||
The Project Sponsor role provides a user with the ability to contribute additional developer resources to the project. Project Sponsors must sign the ICLA. |
||||
|
||||
**Defined by:** Hyperledger |
||||
|
||||
### Requirements |
||||
- Signed ICLA, as described in [CLA.md] |
||||
- Project Sponsor status granted by the Open Source Circle |
||||
|
||||
### Responsibilities and privileges |
||||
- Includes all of the responsibilities and privileges of a Member user |
||||
- Approval of new users to the Approver role, and access to Circle reports. |
||||
|
||||
## Open Source Circle |
||||
The Open Source Circle is a group that provides open source software support to projects. |
||||
**Defined by:** Hyperledger |
||||
|
||||
### Requirements |
||||
- Includes all of the requirements of a Member user |
||||
- Signed ICLA, as described in [CLA.md] |
||||
- Open Source Circle status granted by the Open Source Circle |
||||
|
||||
### Responsibilities and privileges |
||||
- Includes all of the responsibilities and privileges of a Project Sponsor |
||||
- Ability to archive the project |
||||
- Manage the CLA |
||||
- Conduct legal reviews |
||||
|
||||
## Project Evangelist |
||||
The Project Evangelist role is for those who wish to promote the project to the outside world, but not actively contribute to it. |
||||
**Defined by:** Hyperledger |
||||
|
||||
### Requirements |
||||
- Includes all of the requirements of a Member user |
||||
- Signed ICLA, as described in [CLA.md] |
||||
- Project Evangelist status granted by the Open Source Circle |
||||
|
||||
### Responsibilities and privileges |
||||
- Includes all of the responsibilities and privileges of a Member user |
||||
- Project Evangelist have the standard public access permissions |
||||
- Organise talks |
||||
- Work with marketing to manage web and graphical assets |
||||
|
||||
## Benevolent Dictator |
||||
The benevolent dictator, or project lead, is self-appointed. However, because the community always has the ability to fork, this person is fully answerable to the community. The key is to ensure that, as the project expands, the right people are given influence over it and the community rallies behind the vision of the project lead. |
||||
|
||||
### Responsibilities and privileges |
||||
- Set the strategic objectives of the project and communicate these clearly to the community |
||||
- Understand the community as a whole and strive to satisfy as many conflicting needs as possible, while ensuring that the project survives in the long term |
||||
- Ensure that the approvers make the right decisions on behalf of the project |
||||
- Provide final tie-breaker decisions when consensus cannot be reached. |
||||
|
||||
|
||||
## Attribution |
||||
|
||||
This document is adapted from the following sources: |
||||
- Kubernetes community-membership.md, available at [kub community membership]. |
||||
- OSSWatch Benevolent Dictator Governance Model, available at [oss watch benevolent dictator]. |
||||
|
||||
[CLA.md]: /CLA.md |
||||
[oss watch benevolent dictator]: http://oss-watch.ac.uk/resources/benevolentdictatorgovernancemodel |
||||
[kub community membership]: https://raw.githubusercontent.com/kubernetes/community/master/community-membership.md |
||||
[code reviews]: /docs/community/code-reviews.md |
||||
[contributor guide]: /CONTRIBUTING.md |
||||
[New contributors]: /CONTRIBUTING.md |
||||
[two-factor authentication]: https://help.github.com/articles/about-two-factor-authentication |
||||
[besu-dev@pegasys.tech]: mailto:besu-dev@pegasys.tech |
||||
[Besu RocketChat]: https://chat.hyperledger.org/channel/besu |
||||
[Besu Documentation]: https://besu.readthedocs.io/ |
||||
@ -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 |
||||
``` |
||||
Loading…
Reference in new issue