From feee715f6ff78297122f0e743c1172312ebd067c Mon Sep 17 00:00:00 2001 From: Eric Kellstrand <34311165+ekellstrand@users.noreply.github.com> Date: Thu, 11 Oct 2018 16:44:42 -0400 Subject: [PATCH] [NC-1540] First Draft of OSS Roles & Std OSS Documenation (#29) * [NC-1540] First Draft of OSS Roles & Std OSS Documentation - OSS Docs & Templates Signed-off-by: Adrian Sutton --- .github/issue_template.md | 40 ++++ .github/pull_request_template.md | 59 ++++++ CLA.md | 3 + CODE-OF-CONDUCT.md | 74 +++++++ CONTRIBUTING.md | 267 +++++++++++++++++++++--- GOVERNANCE.md | 44 ++++ README.md | 116 ++-------- docs/architecture/architecture.md | 3 + docs/architecture/design-principles.md | 9 + docs/architecture/java-modules.md | 3 + docs/architecture/objectives.md | 8 + docs/community/code-reviews.md | 30 +++ docs/community/community-membership.md | 173 +++++++++++++++ docs/development/building.md | 67 ++++++ docs/development/code-coverage.md | 10 + docs/development/logging.md | 21 ++ docs/development/running-with-gradle.md | 17 ++ 17 files changed, 821 insertions(+), 123 deletions(-) create mode 100644 .github/issue_template.md create mode 100644 .github/pull_request_template.md create mode 100644 CLA.md create mode 100644 CODE-OF-CONDUCT.md create mode 100644 GOVERNANCE.md create mode 100644 docs/architecture/architecture.md create mode 100644 docs/architecture/design-principles.md create mode 100644 docs/architecture/java-modules.md create mode 100644 docs/architecture/objectives.md create mode 100644 docs/community/code-reviews.md create mode 100644 docs/community/community-membership.md create mode 100644 docs/development/building.md create mode 100644 docs/development/code-coverage.md create mode 100644 docs/development/logging.md create mode 100644 docs/development/running-with-gradle.md diff --git a/.github/issue_template.md b/.github/issue_template.md new file mode 100644 index 0000000000..68fad4230e --- /dev/null +++ b/.github/issue_template.md @@ -0,0 +1,40 @@ + + +### Prerequisites + +* [ ] Put an X between the brackets on this line if you have done all of the following: + * Reproduced the issue in the latest version of the software + * Followed all steps in the debugging wiki: https://github.com/PegasysEng/pantheon/wiki/debugging + * Verified the issue doesn't already exist: https://github.com/search?q=+is%3Aissue+repo%3APegasysEng/Pantheon + +### Description + +[Description of the issue] + +### Steps to Reproduce + +1. [Step 1] +2. [Step 2] +3. [Step ...] + +**Expected behavior:** [What you expect to happen] + +**Actual behavior:** [What actually happens] + +**Frequency:** [What percentage of the time does it occur?] + +### Versions + +* Software version `pantheon --version` +* OS Name & Version +* Kernel Version `uname -a` +* Virtual Machine software & version +* Docker Version +* Cloud VM, type, size (eg Amazon Web Services I3-large) + +### Additional Information + +Any additional information, configuration or data that might be necessary to reproduce the issue. \ No newline at end of file diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000000..6383355cd2 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,59 @@ + + +# PR Details + + + +## Description + + + +**Which issue(s) this PR fixes** *(optional, in `fixes #(, fixes #, ...)` format, will close the issue(s) when PR gets merged)*: +Fixes # + +## Related Issue + + + + + + +## Motivation and Context + + + + +## Types of changes + + + +- [ ] Docs change / refactoring / dependency upgrade +- [ ] Bug fix (non-breaking change which fixes an issue) +- [ ] New feature (non-breaking change which adds functionality) +- [ ] Breaking change (fix or feature that would cause existing functionality to change) + +**Special notes for your reviewer**: + +## Release note + +```release-note + +``` + +## Prerequisites: + + +- [ ] I have read the **CONTRIBUTING.md** document. +- [ ] This code follows the style guidelines of this project +- [ ] I have performed a self-review of my own code +- [ ] I have commented my code, particularly in hard-to-understand areas +- [ ] I have made corresponding changes to the documentation +- [ ] My changes generate no new warnings +- [ ] I have added appropriate tests that prove my change is effective +- [ ] New and existing tests pass locally with my changes diff --git a/CLA.md b/CLA.md new file mode 100644 index 0000000000..428d211a15 --- /dev/null +++ b/CLA.md @@ -0,0 +1,3 @@ +**TODO:** + +## Attribution diff --git a/CODE-OF-CONDUCT.md b/CODE-OF-CONDUCT.md new file mode 100644 index 0000000000..dfd1c60cce --- /dev/null +++ b/CODE-OF-CONDUCT.md @@ -0,0 +1,74 @@ +# 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 \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index deffa11ccf..53ae4f7401 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,9 +1,116 @@ # Contributing to Pantheon +:+1::tada: First off, thanks for taking the time to contribute! :tada::+1: -Welcome to the Pantheon repository! This document describes the procedure and guidelines for contributing to the Pantheon project. The subsequent sections encapsulate the criteria used to evaluate additions to, and modifications of, the existing codebase. +Welcome to the Pantheon 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. -## Contributor Workflow +#### Table Of Contents +[Code of Conduct](#code-of-conduct) +[I just have a quick question](#i-just-have-a-quick-question) + +Before You start + * [Pantheon Architecture](docs/architecture/architecture.md) + * [Java Modules](docs/architecture/java-modules.md) + +[How To Contribute](#how-to-contribute) + * [Reporting Bugs](#reporting-bugs) + * [Suggesting Enhancements](#suggesting-enhancements) + * [Your First Code Contribution](#your-first-code-contribution) + * [Pull Requests](#pull-requests) + * [Code Reviews] + +[Style Guides](#Style-Guides) + * [Git Commit Messages & Pull Request Messages](#git-commit-messages--pull-request-messages) + * [Java Style Guide](#java-code-style-guide) + * [Documentation Style Guide](#documentation-style-guide) + +[Issue and Pull Request Labels](#issue-and-pull-request-labels) + +## Code of Conduct + +This project and everyone participating in it is governed by the [Pantheon Code of Conduct](CODE-OF-CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to [private@pegasys.tech]. + + +## 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. + +* [Gitter] +* [Wiki] + +## 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 :pencil:, reproduce the behavior :computer: :computer:, and find related reports :mag_right:. + +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). Fill in the [ISSUE-TEMPLATE.md](.github/issue_template.md), the information it asks for helps us resolve issues faster. + +> **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 the [Debugging Wiki]**. You might be able to find the cause of the problem and fix things yourself. +* **Perform a [cursory search of project issues](https://github.com/search?q=+is%3Aissue+repo%3APegasysEng/Pantheon)** 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 [GitHub issues](https://guides.github.com/features/issues/). Issues should and provide the following information by filling in the [ISSUE-TEMPLATE.md](.github/issue_template.md). + +Explain the problem and include additional details to help maintainers reproduce the problem: + +* **Use a clear and descriptive title** 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 Pantheon, 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 [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines). +* **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 `pantheon -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 pantheon logfile during startup. + +### Suggesting Enhancements + +This section guides you through submitting an enhancement suggestion, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion :pencil: and find related suggestions :mag_right:. + +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). Fill in the [ISSUE-TEMPLATE.md](.github/issue_template.md), including the steps that you imagine you would take if the feature you're requesting existed. + +#### Before Submitting An Enhancement Suggestion + +* **Check the [Debugging Wiki].** You might be able to find the cause of the problem and fix things yourself. +* **Perform a [cursory search of project issues](https://github.com/search?q=+is%3Aissue+repo%3APegasysEng/Pantheon)** 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 [GitHub issues](https://guides.github.com/features/issues/). Issues should and provide the following information by filling in the [ISSUE-TEMPLATE.md](.github/issue_template.md) and providing 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**. Include copy/pasteable snippets which you use in those examples, as [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines). +* **Describe the current behavior** and **explain which behavior you expected to see instead** and why. +* **Include screenshots** which help you demonstrate the steps. +* **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 `pantheon -v` in your terminal. +* **Specify the name and version of the OS you're using.** + +## Your First Code Contribution +Start by looking through the 'beginner' and 'help wanted' issues: +* [Beginner issues][beginner] - issues which should only require a few lines of code, and a test or two. +* [Help wanted issues][help-wanted] - issues which should be a bit more involved than `beginner` issues. + +### Local Development The codebase is maintained using the "*contributor workflow*" where everyone without exception contributes patch proposals using "*pull-requests*". This facilitates social contribution, easy testing and peer review. To contribute a patch, the workflow is as follows: @@ -15,46 +122,158 @@ To contribute a patch, the workflow is as follows: 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. -## Style Guide +### Architectural Best Practices -`La mode se démode, le style jamais.` +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 -Guided by the immortal words of Gabrielle Bonheur, we strive to adhere strictly to best stylistic practices for each line of code in this software. +### Automated Test coverage +Testing is 100% automated for this product. There is no such thing as a manual test. All code submissions must be accompanied by appropriate tests. The goal is to provide confidence in the code’s robustness, while avoiding redundant tests. -At this stage one should expect comments and reviews from fellow contributors. You can add more commits to your pull request by committing them locally and pushing to your fork until you have satisfied all feedback. That being said, before the pull request is merged, it should be squashed. +### Pull Requests -#### Stylistic +The process described here has several goals: -The fundamental resource Pantheon contributors should familiarize themselves with is Oracle's [Code Conventions for the Java TM Programming Language](http://www.oracle.com/technetwork/java/codeconvtoc-136057.html), to establish a general programme on Java coding. Furthermore, all pull-requests should be formatted according to the [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html), as the the [Google Java Style reformatter](https://github.com/google/google-java-format) is a component piece of our continuous integration architecture, code that does not comply stylistically will fail to pass the requisite candidate tests. +- 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 this post: [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/). -#### Architectural Best Practices +Please follow these steps to have your contribution considered by the approvers: -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 +1. Complete the ICLA, as described in [CLA.md] +2. Follow all instructions in [PULL-REQUEST-TEMPLATE.md](.github/pull_request_template.md) +3. Include appropriate test coverage. Testing is 100% automated. There is no such thing as a manual test. +4. Follow the [styleguides](#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 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.
+ +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.md]. + +# 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. + +### Other Java Code Conventions +We have a set of coding conventions that we try to adhere to. These are not strictly enforced during the build, but should be adhered to and called out in code reviews. +* Avoid abbreviations in variable names (ie, use message instead of msg) +* never 2 blank lines in a row + +Exceptions: +* Allowed abbreviation: Tx instead of Transaction (it's historical) + +## Git Commit Messages & Pull Request Messages +* Use the present tense ("Add feature" not "Added feature") +* Use the imperative mood ("Move cursor to..." not "Moves cursor to...") +* Limit the first line to 72 characters or less +* Reference issues and pull requests liberally after the first line +* Consider starting the commit message with an applicable emoji: + * :art: `:art:` when improving the format/structure of the code + * :racehorse: `:racehorse:` when improving performance + * :non-potable_water: `:non-potable_water:` when plugging memory leaks + * :memo: `:memo:` when writing docs + * :penguin: `:penguin:` when fixing something on Linux + * :apple: `:apple:` when fixing something on macOS + * :checkered_flag: `:checkered_flag:` when fixing something on Windows + * :bug: `:bug:` when fixing a bug + * :fire: `:fire:` when removing code or files + * :green_heart: `:green_heart:` when fixing the CI build + * :white_check_mark: `:white_check_mark:` when adding tests + * :lock: `:lock:` when dealing with security + * :arrow_up: `:arrow_up:` when upgrading dependencies + * :arrow_down: `:arrow_down:` when downgrading dependencies + * :shirt: `:shirt:` when removing lint warnings + +## Documentation Style Guide +**TODO: Create Documentation Style Guide** + + +# Issue and Pull Request Labels -#### Clear Commit/PR Messages +This section lists the labels we use to help us track and manage issues and pull requests. -Commit messages should be verbose by default consisting of a short subject line (50 chars max), a blank line and detailed explanatory text as separate paragraph(s), unless the title alone is self-explanatory (such as "`Implement EXP EVM opcode`") in which case a single title line is sufficient. Commit messages should be helpful to people reading your code in the future, so explain the reasoning for your decisions. Further explanation on commit messages can be found [here](https://chris.beams.io/posts/git-commit/). +[GitHub search](https://help.github.com/articles/searching-issues/) makes it easy to use labels for finding groups of issues or pull requests you're interested in. -#### Test coverage +The labels are loosely grouped by their purpose, but it's not required that every issue have a label from every group or that an issue can't have more than one label from the same group. -The test cases are sufficient enough to provide confidence in the code’s robustness, while avoiding redundant tests. +Please open an issue on `PegasysEng/Pantheon` if you have suggestions for new labels. -#### Readability +#### Type of Issue and Issue State -The code is easy to understand. +| Label name | Search Link :mag_right: | Description | +| --- | --- | --- | +| `enhancement` | [search][search-label-enhancement] | Feature requests. | +| `bug` | [search][search-label-bug] | Confirmed bugs or reports that are very likely to be bugs. | +| `question` | [search][search-label-question] | Questions more than bug reports or feature requests (e.g. how do I do X). | +| `feedback` | [search][search-label-feedback] | General feedback more than bug reports or feature requests. | +| `help-wanted` | [search][search-label-help-wanted] | The core team would appreciate help from the community in resolving these issues. | +| `beginner` | [search][search-label-beginner] | Less complex issues which would be good first issues to work on for users who want to contribute. | +| `more-information-needed` | [search][search-label-more-information-needed] | More information needs to be collected about these problems or feature requests (e.g. steps to reproduce). | +| `needs-reproduction` | [search][search-label-needs-reproduction] | Likely bugs, but haven't been reliably reproduced. | +| `blocked` | [search][search-label-blocked] | Issues blocked on other issues. | +| `duplicate` | [search][search-label-duplicate] | Issues which are duplicates of other issues, i.e. they have been reported before. | +| `wontfix` | [search][search-label-wontfix] | The core team has decided not to fix these issues for now, either because they're working as intended or for some other reason. | +| `invalid` | [search][search-label-invalid] | Issues which aren't valid (e.g. user errors). | -#### Simplicity +#### Topic Categories -The code is not over-engineered, sufficient effort is made to minimize the cyclomatic complexity of the software. +| Label name | Search Link :mag_right: | Description | +| --- | --- | --- | +| `windows` | [search][search-label-windows] | Related to running on Windows. | +| `linux` | [search][search-label-linux] | Related to running on Linux. | +| `mac` | [search][search-label-mac] | Related to running on macOS. | +| `documentation` | [search][search-label-documentation] | Related to any type of documentation | +| `performance` | [search][search-label-performance] | Related to performance. | +| `security` | [search][search-label-security] | Related to security. | +| `api` | [search][search-label-api] | Related to public APIs. | -#### Functional +#### Pull Request Labels -Insofar as is possible the code intuitively and expeditiously executes the designated task. +| Label name | Search Link :mag_right: | Description +| --- | --- | --- | +| `work-in-progress` | [search][search-label-work-in-progress] | Pull requests which are still being worked on, more changes will follow. | +| `needs-review` | [search][search-label-needs-review] | Pull requests which need code review, and approval from maintainers or the core team. | +| `under-review` | [search][search-label-under-review] | Pull requests being reviewed by maintainers or the core team. | +| `requires-changes` | [search][search-label-requires-changes] | Pull requests which need to be updated based on review comments and then reviewed again. | -#### Clean -The code is free from glaring typos (*e.g. misspelled comments*), thinkos, or formatting issues (*e.g. incorrect indentation*). +[search-label-enhancement]: https://github.com/search?q=is%3Aopen+is%3Aissue+repo%3APegasysEng%2FPantheon+label%3Aenhancement +[search-label-bug]: https://github.com/search?q=is%3Aopen+is%3Aissue+repo%3APegasysEng%2FPantheon+label%3Abug +[search-label-question]: https://github.com/search?q=is%3Aopen+is%3Aissue+repo%3APegasysEng%2FPantheon+label%3Aquestion +[search-label-feedback]: https://github.com/search?q=is%3Aopen+is%3Aissue+repo%3APegasysEng%2FPantheon+label%3Afeedback +[search-label-help-wanted]: https://github.com/search?q=is%3Aopen+is%3Aissue+repo%3APegasysEng%2FPantheon+label%3Ahelp-wanted +[search-label-beginner]: https://github.com/search?q=is%3Aopen+is%3Aissue+repo%3APegasysEng%2FPantheon+label%3Abeginner +[search-label-more-information-needed]: https://github.com/search?q=is%3Aopen+is%3Aissue+repo%3APegasysEng%2FPantheon+label%3Amore-information-needed +[search-label-needs-reproduction]: https://github.com/search?q=is%3Aopen+is%3Aissue+repo%3APegasysEng%2FPantheon+label%3Aneeds-reproduction +[search-label-triage-help-needed]: https://github.com/search?q=is%3Aopen+is%3Aissue+repo%3APegasysEng%2FPantheon+label%3Atriage-help-needed +[search-label-windows]: https://github.com/search?q=is%3Aopen+is%3Aissue+repo%3APegasysEng%2FPantheon+label%3Awindows +[search-label-linux]: https://github.com/search?q=is%3Aopen+is%3Aissue+repo%3APegasysEng%2FPantheon+label%3Alinux +[search-label-mac]: https://github.com/search?q=is%3Aopen+is%3Aissue+repo%3APegasysEng%2FPantheon+label%3Amac +[search-label-documentation]: https://github.com/search?q=is%3Aopen+is%3Aissue+repo%3APegasysEng%2FPantheon+label%3Adocumentation +[search-label-performance]: https://github.com/search?q=is%3Aopen+is%3Aissue+repo%3APegasysEng%2FPantheon+label%3Aperformance +[search-label-security]: https://github.com/search?q=is%3Aopen+is%3Aissue+repo%3APegasysEng%2FPantheon+label%3Asecurity +[search-label-api]: https://github.com/search?q=is%3Aopen+is%3Aissue+repo%3APegasysEng%2FPantheon+label%3Aapi -#### Appropriately Commented +[search-label-blocked]: https://github.com/search?q=is%3Aopen+is%3Aissue+repo%3APegasysEng%2FPantheon+label%3Ablocked +[search-label-duplicate]: https://github.com/search?q=is%3Aopen+is%3Aissue+repo%3APegasysEng%2FPantheon+label%3Aduplicate +[search-label-wontfix]: https://github.com/search?q=is%3Aopen+is%3Aissue+repo%3APegasysEng%2FPantheon+label%3Awontfix +[search-label-invalid]: https://github.com/search?q=is%3Aopen+is%3Aissue+repo%3APegasysEng%2FPantheon+label%3Ainvalid +[search-label-work-in-progress]: https://github.com/search?q=is%3Aopen+is%3Apr+repo%3APegasysEng%2FPantheon+label%3Awork-in-progress +[search-label-needs-review]: https://github.com/search?q=is%3Aopen+is%3Apr+repo%3APegasysEng%2FPantheon+label%3Aneeds-review +[search-label-under-review]: https://github.com/search?q=is%3Aopen+is%3Apr+repo%3APegasysEng%2FPantheon+label%3Aunder-review +[search-label-requires-changes]: https://github.com/search?q=is%3Aopen+is%3Apr+repo%3APegasysEng%2FPantheon+label%3Arequires-changes +[beginner]:https://github.com/search?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3Abeginner+label%3Ahelp-wanted+repo%3APegasysEng%2FPantheon+sort%3Acomments-desc +[help-wanted]:https://github.com/search?q=is%3Aopen+is%3Aissue+label%3Ahelp-wanted+repo%3APegasysEng%2FPantheon+sort%3Acomments-desc+-label%3Abeginner -Ambiguous or unclear code segments are commented. The comments are written in complete sentences. +[private@pegasys.tech]: mailto:private@pegasys.tech +[Gitter]: https://gitter.im/Pantheon +[Wiki]: https://github.com/PegaSysEng/pantheon/wiki +[Debugging Wiki]: https://github.com/PegaSysEng/pantheon/wiki/Debugging +[CLA.md]: /CLA.md +[code-reviews.md]: /docs/community/code-reviews.md \ No newline at end of file diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 0000000000..060a4c453a --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,44 @@ +This is a Work in Progress, documenting approximately how we have been operating up to this point. + +# Overview +This project is led by a benevolent dictator (PegaSys) and managed by the community. That is, the community actively contributes to the day-to-day maintenance of the project, but the general strategic line is drawn by the benevolent dictator. In case of disagreement, they have the last word. It is the benevolent dictator’s job to resolve disputes within the community and to ensure that the project is able to progress in a coordinated way. In turn, it is the community’s job to guide the decisions of the benevolent dictator through active engagement and contribution. + + +# Principles + +The community adheres to the following principles: +* Open: Pantheon is open source. See repository guidelines and CLA, below. +* Welcoming and respectful: See Code of Conduct, below. +* Transparent and accessible: Work and collaboration should be done in public. +* Merit: Ideas and contributions are accepted according to their technical merit and alignment with project [objectives], [scope], and [design principles]. + +# Code of Conduct +See [code of conduct] + +# Community membership + +See [community membership] + +# Decision Making +Decision making will be handled by the Approvers (see [community membership]). If consensus cannot be reached, the Benevolent Dictator will provide the final word on the decision. + + +# CLA + +All contributors must sign the CLA, as described in [CLA.md]. +## Attribution + +This document was influenced by the following: +- Kubernetes community-membership.md, available at [kub community membership]. +- Kubernetes governance.md, available at [kub governance] +- OSSWatch Benevolent Dictator Governance Model, available at [oss watch benevolent dictator]. + +[CLA.md]: /CLA.md +[objectives]: /docs/architecture/objectives.md +[scope]: /docs/architecture/objectives.md +[design principles]: /docs/architecture/design-principles.md +[community membership]: /docs/community/community-membership.md +[code of conduct]: /CODE-OF-CONDUCT.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 +[kub governance]:https://github.com/kubernetes/community/blob/master/governance.md diff --git a/README.md b/README.md index 048f91b18c..16519f4519 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,9 @@ -# Pantheon Ethereum Client · [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE) +# Pantheon Ethereum Client + [![Build Status](http://forge-jenkins.kellstrand.com:8080/job/Pantheon/job/master/badge/icon)](http://forge-jenkins.kellstrand.com:8080/job/Pantheon/job/master/) + [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/PegasysEng/pantheon/blob/master/LICENSE) + [![Download](https://api.bintray.com/packages/consensys/binaries/pantheon/images/download.svg)](https://bintray.com/consensys/binaries/pantheon/_latestVersion) + + TODO: Update Download links once artifacts are on bintray ## Pantheon Users @@ -19,104 +24,17 @@ User and reference documentation available on the Wiki includes: ## Pantheon Developers -## Build Instructions +* [Contribution Guidelines](CONTRIBUTING.md) +* [Wiki](wiki/) for installation & configuring Pantheon +* [Installation](wiki/Installation) -To build, clone this repo and run with `./gradlew` like so: +### Development +Instructions for how to get started with developing on the Orion codebase. Please also read the +[contribution guidelines](CONTRIBUTING.md) for more detail on how to submit a pull request (PR). -``` -git clone --recursive https://github.com/PegaSysEng/pantheon.git -cd pantheon -./gradlew -``` +* [Installation](wiki/Installation) +* [Checking out and building](docs/development/building.md) +* [Running Pantheon via Gradle](docs/development/running-with-gradle.md) +* [Code Coverage](docs/development/code-coverage.md) +* [Logging](docs/development/logging.md) -After a successful build, distribution packages will be available in `build/distribution`. - -## Code Style - -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. - -## Testing - -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 -``` - -## Running Pantheon - -You can build and run Pantheon with default options via: - -``` -./gradlew run -``` - -By default this stores all persistent data in `build/pantheon`. - -If you want to set custom CLI arguments for the Pantheon execution, you can use the property `pantheon.run.args` like e.g.: - -```sh -./gradlew run -Ppantheon.run.args="--discovery=false --home=/tmp/pantheontmp" -``` - -which will pass `--discovery=false` and `--home=/tmp/pantheontmp` to the invocation. - -### 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:net.consensys.pantheon.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:net.consensys.pantheon.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. - -### 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: - -``` -ALL: All levels including custom levels. -DEBUG: Designates fine-grained informational events that are most useful to debug an application. -ERROR: Designates error events that might still allow the application to continue running. -FATAL: Designates very severe error events that will presumably lead the application to abort. -INFO: Designates informational messages that highlight the progress of the application at coarse-grained level. -OFF: The highest possible rank and is intended to turn off logging. -TRACE: Designates finer-grained informational events than the DEBUG. -WARN: Designates potentially harmful situations. -``` - -One mechanism of globally effecting the log output of a running client is though modification the file -`/pantheon/src/main/resources/log4j2.xml`, where it can be specified under the ``. -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. - -## Contribution - -Welcome to the Pantheon Ethereum project repo. If you would like to help contribute -code to the project, please fork, commit and send us a pull request. - -Please read the [Contribution guidelines](docs/CONTRIBUTORS.md) for this project. diff --git a/docs/architecture/architecture.md b/docs/architecture/architecture.md new file mode 100644 index 0000000000..428d211a15 --- /dev/null +++ b/docs/architecture/architecture.md @@ -0,0 +1,3 @@ +**TODO:** + +## Attribution diff --git a/docs/architecture/design-principles.md b/docs/architecture/design-principles.md new file mode 100644 index 0000000000..f581bfa364 --- /dev/null +++ b/docs/architecture/design-principles.md @@ -0,0 +1,9 @@ + +**TODO:** + +## Attribution + +This document was influenced by the following: +- Kubernetes principles.md, available at [kub governance] + +[kub governance]: https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture/principles.md diff --git a/docs/architecture/java-modules.md b/docs/architecture/java-modules.md new file mode 100644 index 0000000000..428d211a15 --- /dev/null +++ b/docs/architecture/java-modules.md @@ -0,0 +1,3 @@ +**TODO:** + +## Attribution diff --git a/docs/architecture/objectives.md b/docs/architecture/objectives.md new file mode 100644 index 0000000000..7d214d08ca --- /dev/null +++ b/docs/architecture/objectives.md @@ -0,0 +1,8 @@ +**TODO:** + +## Attribution + +This document was influenced by the following: +- Kubernetes governance.md, available at [kub governance] + +[kub governance]: https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture/principles.md diff --git a/docs/community/code-reviews.md b/docs/community/code-reviews.md new file mode 100644 index 0000000000..fc2a9204a2 --- /dev/null +++ b/docs/community/code-reviews.md @@ -0,0 +1,30 @@ +## Code reviews + +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 [Pantheon Gitter] + +Except for rare cases, such as trivial changes (e.g. typos, comments) or +emergencies (e.g. broken builds), approvers should not merge their own +changes without another approver providing the code review. + +## 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 +[Pantheon Gitter]: https://gitter.im/Pantheon \ No newline at end of file diff --git a/docs/community/community-membership.md b/docs/community/community-membership.md new file mode 100644 index 0000000000..0f359c72e6 --- /dev/null +++ b/docs/community/community-membership.md @@ -0,0 +1,173 @@ +# Community membership + +**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 | Pantheon GitHub org member +| Approver | approve accepting contributions | write permissions on master +| Project Manager | management of the project | **TODO:** +| Project Sponsor | contribute developer resources | **TODO:** +| Open Source Circle | OSS support | **TODO:** +| Project Evangelist | promote the project | **TODO:** +| Benevolent Dictator | decision tie-breaker | PegaSys + +## 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 community discussions (e.g. meetings, Slack, email discussion forums, Stack Overflow) +- Subscribed to [pantheon-dev@pegasys.tech] +- Joined [Pantheon Gitter] +- Browsed [Pantheon 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:** TODO: Where do we document this? + +### 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:** TODO: Where do we document this? + +### 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:** **TODO:** Where do we document this? + +### 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:** TODO: Where do we document this? + +### 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 +[pantheon-dev@pegasys.tech]: mailto:pantheon-dev@pegasys.tech +[Pantheon Gitter]: https://gitter.im/Pantheon +[Pantheon Wiki]: https://github.com/PegaSysEng/pantheon/wiki diff --git a/docs/development/building.md b/docs/development/building.md new file mode 100644 index 0000000000..fce7b062fa --- /dev/null +++ b/docs/development/building.md @@ -0,0 +1,67 @@ +# Checkout code and build it +## Checkout source code + +``` +git clone --recursive git@github.com:PegasysEng/Pantheon.git +``` +OR +``` +git clone --recursive https://github.com/PegasysEng/pantheon +``` + +## See what tasks are available +To see all of the gradle tasks that are available: +``` +cd pantheon +./gradlew tasks +``` + + +## Build from source +After you have checked out the code, this will build the distribution binaries. +``` +cd pantheon +./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:net.consensys.pantheon.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:net.consensys.pantheon.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. + diff --git a/docs/development/code-coverage.md b/docs/development/code-coverage.md new file mode 100644 index 0000000000..3815f6919c --- /dev/null +++ b/docs/development/code-coverage.md @@ -0,0 +1,10 @@ +## 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 +``` + +The report will be available at `build/reports/jacoco/test/html/index.html` \ No newline at end of file diff --git a/docs/development/logging.md b/docs/development/logging.md new file mode 100644 index 0000000000..7ce6b5b2a7 --- /dev/null +++ b/docs/development/logging.md @@ -0,0 +1,21 @@ +# 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 +`/pantheon/src/main/resources/log4j2.xml`, where it can be specified under the ``. +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. + diff --git a/docs/development/running-with-gradle.md b/docs/development/running-with-gradle.md new file mode 100644 index 0000000000..0eced75b27 --- /dev/null +++ b/docs/development/running-with-gradle.md @@ -0,0 +1,17 @@ +# Running Pantheon + +You can build and run Pantheon with default options via: + +``` +./gradlew run +``` + +By default this stores all persistent data in `build/pantheon`. + +If you want to set custom CLI arguments for the Pantheon execution, you can use the property `pantheon.run.args` like e.g.: + +```sh +./gradlew run -Ppantheon.run.args="--discovery=false --home=/tmp/pantheontmp" +``` + +which will pass `--discovery=false` and `--home=/tmp/pantheontmp` to the invocation.