diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 691039b20f..ff0bea29b7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,9 @@ # Contributing to Pantheon :+1::tada: First off, thanks for taking the time to contribute! :tada::+1: -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. +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. #### Table Of Contents [Code of Conduct](#code-of-conduct) @@ -11,7 +13,7 @@ Welcome to the Pantheon repository! The following is a set of guidelines for co [How To Contribute](#how-to-contribute) * [Reporting Bugs](#reporting-bugs) * [Suggesting Enhancements](#suggesting-enhancements) - * [Your First Code Contribution](#your-first-code-contribution) + * [Your First Contribution](#your-first-contribution) * [Pull Requests](#pull-requests) * [Code Reviews] @@ -24,110 +26,171 @@ Welcome to the Pantheon repository! The following is a set of guidelines for co ## 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]. +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. +* [Pantheon documentation] * [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, reproduce the behavior, and find related reports. +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). Fill in the [issue_template.md](.github/issue_template.md), the information it asks for helps us resolve issues faster. +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. +> **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. +* **Check the [Debugging documentation]**. 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 provide the following information by filling in the [issue_template.md](.github/issue_template.md). +Bugs are tracked as [GitHub issues](https://guides.github.com/features/issues/). +Issues should 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. +* **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. +* **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 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. +* **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 and find related suggestions. +This section guides you through submitting an enhancement suggestion, including completely new features +and minor improvements to existing functionality or documentation changes. -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. +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). +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. +* **Check the [Debugging documentation].** 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: +Enhancement suggestions are tracked as [GitHub issues](https://guides.github.com/features/issues/). +Issues should 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). +* **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 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 'good first issue' and 'help wanted' issues: -* [Good First Issue][search-label-good-first-issue] - issues which should only require a few lines of code, and a test or two. +## Your First Contribution +Start by looking through the 'good first issue' and 'help wanted' labeled issues: +* [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. -### 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: - -* Fork repository -* Create topic branch -* Commit patch -* Create pull-request, adhering to the coding conventions herein set forth - -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. +### 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/pantheon/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 and documentation conventions described below. +_In general a commit serves a single purpose and diffs should be easily comprehensible. +For this reason do not mix any formatting fixes or code moves with actual code changes._ +1. **Commit your changes** using a clear commit message. +1. **Test your changes** locally before pushing to ensure that what you are proposing is not breaking +another part of the software. + * For code changes, 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. + * For doc changes, displaying the doc with [MkDocs] in a preview mode enables you to check the + rendering as explained in the [MkDocs And Markdown Guide](MKDOCS-MARKDOWN-GUIDE.md#preview-the-documentation). +1. **Push your changes** to your remote fork (usually labeled as `origin`). +1. **Create a pull-request** (PR) on the Pantheon repository. +1. **Add labels** to identify the type of your PR. _For example, if your PR only changes documentation, add the +"documentation" label. If it fixes a bug, add the "bug" label._ +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 Pantheon ! 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 +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. +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. >**Important** -> The [`libsodium`](https://download.libsodium.org/doc/installation) library must be installed to run `./gradlew integrationTest`. - +> The [`libsodium`](https://download.libsodium.org/doc/installation) library must be installed to +run `./gradlew integrationTest`. ### Pull Requests @@ -137,17 +200,26 @@ The process described here has several goals: - 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/). +- Further explanation on PR & commit messages can be found in this post: +[How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/). Please follow these steps to have your contribution considered by the approvers: -1. Complete the CLA, 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 [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 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]. +1. Complete the CLA, 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 [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 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]. # Style Guides @@ -162,7 +234,17 @@ We use Google's Java coding conventions for the project. To reformat code, run: 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. +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. + +## Documentation Style Guide +For documentation, we have [documentation guidelines and examples](DOC-STYLE-GUIDE.md). +These rules are not automatically enforced but are recommended to make the documentation consistent + and enhance the user experience. + +Also have a look at our [MKDocs Markdown guide](MKDOCS-MARKDOWN-GUIDE.md) if you're not famililar with +MarkDown syntax. We also have a number of extensions that are available in the Pantheon documentation described +in this guide. ## Git Commit Messages & Pull Request Messages * Use the present tense ("Add feature" not "Added feature") @@ -173,65 +255,66 @@ We have a set of [coding conventions](CODING-CONVENTIONS.md) to which we try to # Issue and Pull Request Labels #### Type of Issue and Issue State -| 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. | -| `help wanted` | [search][search-label-help-wanted] | The core team would appreciate help from the community in resolving these issues. | -| `good first issue` | [search][search-label-good-first-issue] | Less complex issues which would be good first issues to work on for users who want to contribute. | -| `info needed` | [search][search-label-info-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). | -| `do we want this?` | [search][search-label-do-we-want-this] | Seeking stakeholder consensus on proposed feature. | +| Label name | Description | +|---------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------| +| [`enhancement`][search-label-enhancement] | Feature requests. | +| [`bug` ][search-label-bug] | Confirmed bugs or reports that are very likely to be bugs. | +| [`help wanted`][search-label-help-wanted] | The core team would appreciate help from the community in resolving these issues. | +| [`good first issue`][search-label-good-first-issue] | Less complex issues which would be good first issues to work on for users who want to contribute. | +| [`info needed`][search-label-info-needed] | More information needs to be collected about these problems or feature requests (e.g. steps to reproduce). | +| [`needs reproduction`][search-label-needs-reproduction] | Likely bugs, but haven't been reliably reproduced. | +| [`blocked`][search-label-blocked] | Issues blocked on other issues. | +| [`duplicate`][search-label-duplicate] | Issues which are duplicates of other issues, i.e. they have been reported before. | +| [`wontfix`][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-label-invalid] | Issues which aren't valid (e.g. user errors). | +| [`do we want this?`][search-label-do-we-want-this] | Seeking stakeholder consensus on proposed feature. | | #### Topic Categories -| 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. | +| Label name | Description | +|-----------------------------------------------|--------------------------------------| +| [`windows`][search-label-windows] | Related to running on Windows. | +| [`linux`][search-label-linux] | Related to running on Linux. | +| [`mac`][search-label-mac] | Related to running on macOS. | +| [`documentation`][search-label-documentation] | Related to any type of documentation | +| [`performance`][search-label-performance] | Related to performance. | +| [`security`][search-label-security] | Related to security. | +| [`api`][search-label-api] | Related to public APIs. | #### Pull Request Labels -| 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. | -| `requires-changes` | [search][search-label-requires-changes] | Pull requests which need to be updated based on review comments and then reviewed again. | - -[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 - -[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-help-wanted]: https://github.com/search?q=is%3Aopen+is%3Aissue+repo%3APegasysEng%2FPantheon+label%3Ahelp%20wanted -[search-label-good-first-issue]: https://github.com/PegasysEng/pantheon/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22 -[search-label-info-needed]: https://github.com/search?q=is%3Aopen+is%3Aissue+repo%3APegasysEng%2FPantheon+label%3Ainfo%20needed -[search-label-needs-reproduction]: https://github.com/search?q=is%3Aopen+is%3Aissue+repo%3APegasysEng%2FPantheon+label%3Aneeds%20reproduction -[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-do-we-want-this]: https://github.com/search?q=is%3Aopen+is%3Aissue+repo%3APegasysEng%2FPantheon+label%3Ado%20we%20want%20this -[search-label-work-in-progress]: https://github.com/search?q=is%3Aopen+is%3Apr+repo%3APegasysEng%2FPantheon+label%3Awork%20in%20progress -[search-label-requires-changes]: https://github.com/search?q=is%3Aopen+is%3Apr+repo%3APegasysEng%2FPantheon+label%3Arequires%20changes - +| 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. | + +[search-label-windows]: https://github.com/PegaSysEng/pantheon/issues?q=is%3Aopen+is%3Aissue+label%3A%22windows%22 +[search-label-linux]: https://github.com/PegaSysEng/pantheon/issues?q=is%3Aopen+is%3Aissue+label%3A%22linux%22 +[search-label-mac]: https://github.com/PegaSysEng/pantheon/issues?q=is%3Aopen+is%3Aissue+label%3A%22mac%22 +[search-label-documentation]: https://github.com/PegaSysEng/pantheon/issues?q=is%3Aopen+is%3Aissue+label%3A%22documentation%22 +[search-label-performance]: https://github.com/PegaSysEng/pantheon/issues?q=is%3Aopen+is%3Aissue+label%3A%22performance%22 +[search-label-security]: https://github.com/PegaSysEng/pantheon/issues?q=is%3Aopen+is%3Aissue+label%3A%22security%22 +[search-label-api]: https://github.com/PegaSysEng/pantheon/issues?q=is%3Aopen+is%3Aissue+label%3A%22api%22 +[search-label-enhancement]: https://github.com/PegaSysEng/pantheon/issues?q=is%3Aopen+is%3Aissue+label%3A%22enhancement%22 +[search-label-bug]: https://github.com/PegaSysEng/pantheon/issues?q=is%3Aopen+is%3Aissue+label%3A%22bug%22 +[search-label-help-wanted]: https://github.com/PegaSysEng/pantheon/issues?q=is%3Aopen+is%3Aissue+label%3A%22help%20wanted%22 +[search-label-good-first-issue]: https://github.com/PegaSysEng/pantheon/issues?q=is%3Aopen+is%3Aissue+label%3A%22good%20first%20issue%22 +[search-label-info-needed]: https://github.com/PegaSysEng/pantheon/issues?q=is%3Aopen+is%3Aissue+label%3A%22info%20needed%22 +[search-label-needs-reproduction]: https://github.com/PegaSysEng/pantheon/issues?q=is%3Aopen+is%3Aissue+label%3A%22needs%20reproduction%22 +[search-label-blocked]: https://github.com/PegaSysEng/pantheon/issues?q=is%3Aopen+is%3Aissue+label%3A%22blocked%22 +[search-label-duplicate]: https://github.com/PegaSysEng/pantheon/issues?q=is%3Aopen+is%3Aissue+label%3A%22duplicate%22 +[search-label-wontfix]: https://github.com/PegaSysEng/pantheon/issues?q=is%3Aopen+is%3Aissue+label%3A%22wontfix%22 +[search-label-invalid]: https://github.com/PegaSysEng/pantheon/issues?q=is%3Aopen+is%3Aissue+label%3A%22invalid%22 +[search-label-do-we-want-this]: https://github.com/PegaSysEng/pantheon/issues?q=is%3Aopen+is%3Aissue+label%3A%22do%20we%20want%20this%22 +[search-label-work-in-progress]: https://github.com/PegaSysEng/pantheon/pulls?q=is%3Aopen+is%3Apr+label%3A%22work%20in%20progress%22 +[search-label-requires-changes]: https://github.com/PegaSysEng/pantheon/pulls?q=is%3Aopen+is%3Apr+label%3A%22requires%20changes%22 +[search-label-needs-engineering-approval]: https://github.com/PegaSysEng/pantheon/pulls?q=is%3Aopen+is%3Apr+label%3A%22needs+engineering+approval%22 [private@pegasys.tech]: mailto:private@pegasys.tech [Gitter]: https://gitter.im/PegaSysEng/pantheon -[Wiki]: https://github.com/PegaSysEng/pantheon/wiki -[Debugging Wiki]: https://github.com/PegaSysEng/pantheon/wiki/Debugging +[Pantheon documentation]: https://docs.pantheon.pegasys.tech/ +[Debugging documentation]: https://docs.pantheon.pegasys.tech/en/stable/Using-Pantheon/Debugging/ [CLA.md]: /CLA.md -[Code Reviews]: /docs/community/code-reviews.md \ No newline at end of file +[Code Reviews]: /docs/community/code-reviews.md +[MkDocs]: https://www.mkdocs.org/ \ No newline at end of file diff --git a/DOC-STYLE-GUIDE.md b/DOC-STYLE-GUIDE.md new file mode 100644 index 0000000000..2609b0b953 --- /dev/null +++ b/DOC-STYLE-GUIDE.md @@ -0,0 +1,110 @@ +# Pantheon Documentation Style Guide + +## Purpose of this Document + +This document contains guidelines to ensure the Pantheon documentation is consistent and well organised. + +This is a living document and will evolve to better suit Pantheon users and contributors needs. + +> **Note:** Although not everything in this style guide is currently followed in the Pantheon +documention, these guidelines are intended to be applied when writing new content and revising +existing content. + +**The primary audience for this document is:** + +* Members of the Pantheon team +* Developers and technical writers contributing to the Pantheon documentation + +## Mission Statement + +The Pantheon documentation contributes to a consistent and easy to understand experience for end users. +We're focused on creating a great experience for both new and expert users of Ethereum clients. + +## General Guidelines + +The guiding principles for the Pantheon documentation are: +1. Be consistent +1. Keep it simple but technically correct +1. Be proactive and suggest good practices +1. Be informative and exhaustive. + +### 1. Be Consistent + +Consistency is important to help our end users build a mental model of how Pantheon works. +By being consistent with our word choices, visual formatting, and style of communication it helps +users know what to expect when they refer to or search Pantheon documentation. + +### 2. Keep It Simple But Technically Correct + +Avoid technical jargon and always assume our end users may not be Ethereum experts. + +This doesn't mean explaining all Ethereum concepts in our documentation. Explain Pantheon functionality +and when an understanding of complex Ethereum concepts is required refer users to relevant resources. + +For example, to explain how the EVM works, link to ethdocs.org documentation such as +http://ethdocs.org/en/latest/introduction/what-is-ethereum.html#ethereum-virtual-machine + +Simple explanations must still be technically correct. + +### 3. Be Proactive And Suggest Good Practices + +Being proactive means anticipating user needs and guiding them through a process. +This most often takes the form of notes or tip messages alongside the main explanation. +Put yourself in the user's shoes and consider what questions you would have when reading the documentation. + +Do not assume required steps are implied. Err on the side of including them if you are unsure. + +Documenting good practices is also important. +For example, instruct users to secure private keys and protect RPC endpoints a production environments. + +### 4. Be Informative But Concise + +We seek a balance between providing enough relevant information to help our users develop a solid +mental model of how Pantheon works without forcing them to read too much text or redundant detail. + +To provide additional detail, use sub-sections. + +## Writing Style Guide + +We use the [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/) as our general guide +to writing technical documentation. +We take guidance from it but do not apply every rule. +For example, we use title case rather than sentence case. + +The Micrsoft Style Guide aims for natural, simple, and clear communication. + +Here are some important points we follow: + +### Active Voice +Use active voice. Use _you_ to create a more personal friendly style. Avoid gendered pronouns (_he_ or _she_). + +### Contractions +Use contractions. For example, don’t. + +Use common contractions, such as it’s and you’re, to create a friendly, informal tone. + +### Recommend +It's acceptable to use "we recommend" to introduce a product recommendation. +Don't use "PegaSys recommends" or "it is recommended." + +Example: Instead of _This is not recommended for production code_ use _We don't recommend this for production code_. + +### Directory vs Folder +Use _directory_ over _folder_ because we are writing for developers. + +### Title Case For Headings +Use title case for headings. + +Note: This is a case where we are not following the Microsoft Writing Style Guide. + +### Assumed Knowledge For Readers +We have two distinct audiences to consider when developing content: + +- New to Ethereum and Ethereum clients +- Experienced with Ethereum clients other than Pantheon. + +### Avoid Abbreviations + +Try not to use abbreviations [except for well known ones and some jargon](MKDOCS-MARKDOWN-GUIDE.md#abbreviations). +Don't use "e.g." but use "for example". +Don't use "i.e." but use "that is". \ No newline at end of file diff --git a/MKDOCS-MARKDOWN-GUIDE.md b/MKDOCS-MARKDOWN-GUIDE.md new file mode 100644 index 0000000000..84c98350cf --- /dev/null +++ b/MKDOCS-MARKDOWN-GUIDE.md @@ -0,0 +1,392 @@ +# MkDocs And Markdown Guide + +Pantheon documentation is written using [Markdown](https://daringfireball.net/projects/markdown/) syntax. + +However, we use two flavors of this syntax: + +- One for pages inside the [/docs](/docs) directory that will be rendered by [MkDocs] as described below +in the [Installed Markdown Extensions](#installed-markdown-extensions) section. +- Another using the [Github syntax](https://guides.github.com/features/mastering-markdown/) +for pages outside of this documentation directory. These are mainly files to support our [open source +community](https://github.com/PegaSysEng/pantheon/community). + +## MkDocs Documentation Website + +The [Pantheon documentation website](https://docs.pantheon.pegasys.tech/) is maintained by PegaSys from +the content of the [/docs](/docs) directory. + +### /docs Directory + +The [/docs](/docs) directory in the Pantheon repository contains all the documentation that +is generated into a static HTML website using [MkDocs] and the [Mkdocs Material] theme and hosted by [readthedocs.org]. + +The documentation is automatically updated using [WebHooks](https://docs.readthedocs.io/en/stable/webhooks.html) +linking GitHub to the [readthedocs.org] site when you merge a pull-request in the master branch of Pantheon. + +The system also detects tags in the Github repository and takes care of making the latest stable release +and previous versions available. + +If any issues occur, contact the maintainers of the [Pantheon documentation project](https://readthedocs.org/projects/pantheon/). + +### MkDocs Configuration + +[MkDocs] is a Python tool that generates the static HTML website that is published. + +Our [MkDocs] setup uses a [Mkdocs Material] theme to render the html pages. It also comes with a number of useful extensions. + +[MkDocs] in configured in the [mdkocs.yml](/mkdocs.yml) file. + +This file configures: + +- Site meta data and variables +- Theme configuration +- Page navigation +- Extensions +- Plugins + +If you add pages to the documentation (rather than updating existing pages), update the "nav" section +to add your page and specify the page name. + +### Preview The Documentation + +We recommended previewing your work locally before pushing your changes within a pull-request. +As the final documentation is build with [MkDocs], you have to build your docs locally with this tool +to ensure the Markdown is correctly understood and displayed. + +To preview Pantheon documentation locally: + +- [Install Python](https://www.mkdocs.org/#installing-python) +- [Install PIP](https://www.mkdocs.org/#installing-pip) +- Install all the required dependencies : + ```bash + pip install -r docs/requirements.txt + ``` +- Run the following command in the project directory : + ```bash + mkdocs serve + ``` +- Follow the link displayed on the output of this command that +looks like `[I 190206 18:48:47 server:298] Serving on http://127.0.0.1:8000`, +here connect to [http://127.0.0.1:8000] + +You can let this doc server run while you work on the doc, it updates the local website +automatically when you save changes in your Markdown files. + +## Formatting Markdown For Doc Site + +Final documentation rendering is essential, but the format of the Markdown files is also very important. + +Formatting the Markdown code helps reviewers and writers easily navigate in the code and review your changes. + +A few basic rules: + +- Each file must contain a header composed of [meta-data](https://squidfunk.github.io/mkdocs-material/extensions/metadata/) +and ended by a specific comment. + Ex: + ```markdown + title: Installation overview + description: Overview and requirements to install Pantheon + + ``` +- [As for other code](https://google.github.io/styleguide/javaguide.html#s4.4-column-limit), +each line of Markdown code must be limited to 100 columns long to be readable on any editor. +Lines have to be wrapped without cutting the line in the middle of a word. A line break displays as a space. +- No HTML markup can be used inside a Markdown document. +We provide [a lot of extensions](#installed-markdown-extensions) that are able to do the same thing +without HTML. If you think one is missing, just discuss it with the team on [Gitter] and we'll decide together +if it's worth adding an extension. +- Only one first level title can be present on a page. +- Format tables so they are also readable in the source code. +You can quickly achieve this by using a tool like http://markdowntable.com/ + +## Installed Markdown Extensions + +>**Important** +> Extensions are only available for the docs under [/docs](/docs) directory. + +As markdown can be a bit limited when it comes to some specific rendering of code, TOCs, and other documentation +elements, we configured some extensions for these items. +Extensions enable you to use simple Markdown syntax to achieve some complex rendering. + +>**Important** +> Never use HTML tags directly in the Markdown files to try to render content. +For consistency reasons we only allow the specific renderings available in the extensions. + +Here is a list of the available extensions: + +### TOC + +This extension automatically displays a table of content of the current page on the right side of the page. +It displays titles to the third level (`###`). After the third level, titles won't be displayed in the TOC. + +This extension also displays a link on the right of any title called "permalink". +This link can be used to point directly to the title from another website. + +### Highlight + +This extension enables automatic syntax highlighting of code blocks. Define the language to ensure correct +highlighting. If you don't provide the language name, the extension attempts to automatically discover it +but this can lead to errors. + +Example: +````markdown +```json +{ + "jsonrpc" : "2.0", + "id" : 51, + "result" : { + "startingBlock" : "0x5a0", + "currentBlock" : "0xad9", + "highestBlock" : "0xad9" + } +} +``` +```` + +Pygment is the implementation for this extension, refer to Pygment website for a +[list of the supported languages](http://pygments.org/languages/). + +### Include + +If you have content to be repeated on multiple pages, you can create it in a common page in and include +it in all required pages. + +Example: +To include the content of the "test_accounts.md" page in the "/docs/global" directory in another page, use: +```markdown +{!global/test_accounts.md!} +``` + +### Admonition + +The [Admonition extension](https://squidfunk.github.io/mkdocs-material/extensions/admonition/#admonition) +enables information, warning, and danger blocks. + +Example: +````markdown +!!! note + This is a multi line note + in the Pantheon documentation. +```` + +The 4 spaces indentation is required for the content to be part of the admonition. + +We generally use the following [types](https://squidfunk.github.io/mkdocs-material/extensions/admonition/#types) +in our documentation: + +- **Note** : Used to add information about a subject that doesn't directly needs to be taken in account +to use this specific part. +Example: "Available since v0.8.3" +- **Abstract** : Used at the beginning of a long article. Also known as "TL;DR", this can help users jump +into the content knowing that they will find their answer somewhere in the page. +- **Info** : Used to provide detail about a specific part of the documentation. +Ex: "The miner coinbase account is one of the accounts defined in the genesis file." +- **Tip** : Used to provide information that could help improve the use of the tool, make it faster. +Example: "To restart the private network in the future, start from 4. Restart First Node as Bootnode." +- **Warning** : Used to warn the users about something important. +Ex: "This will be deprecated in next version." +- **Danger** : Used to alert the user about a potential dangerous effect such as a risk of destroying +something or losing assets. +Ex: "Never use the development private keys for production use". +- **Example** : used to display an example. We usually use it with a single or tabbed code-block: +````markdown +!!! example + This example shows how to use the `net_listening` RPC method. + + ```bash tab="curl HTTP request" + $ curl -X POST --data '{"jsonrpc":"2.0","method":"net_listening","params":[],"id":53}' + ``` + + ```bash tab="wscat WS request" + {"jsonrpc":"2.0","method":"net_listening","params":[],"id":53} + ``` + + ```json tab="JSON result" + { + "jsonrpc" : "2.0", + "id" : 53, + "result" : true + } + ``` +```` + +### Footnotes + +The [Footnotes extension](https://squidfunk.github.io/mkdocs-material/extensions/footnotes/) enables +adding footnotes. + +Footnotes display content at the end of the page and a numbered link inside the text to go to this content. +The extension also adds a link at the end of the footnote back to the text. + +### Definitions List + +The [def_list extension](https://python-markdown.github.io/extensions/definition_lists/) enables listing definitions +directly in the Markdown. + +### Abbreviations + +Generally we avoid the use of abbreviations but some like "PoW" for proof-of-work or "dApp" for +decentralized application are now part of the Ethereum jargon. The [Abbreviation extension](https://python-markdown.github.io/extensions/abbreviations/) +enables a tool tip hint to be provided for abbreviations. + +Place abbreviations at the beginning of the Markdown file just after the meta-data header. + +Example: +```markdown +description: This is an example page + + +*[PoA]: Proof of Work + +Clique is a PoA mechanism used in the Rinkeby test network +``` + +### Math + +[Arithmatex extension](https://squidfunk.github.io/mkdocs-material/extensions/pymdown/#arithmatex-mathjax ) +enables writing math formulas in the documentation using the provided syntax. + +Example: +```markdown +$\sigma=\displaystyle\prod_{k=1}^t\sigma_{i_k}^{L_{i_k}(0)}$ + +Constructing the threshold signature $\sigma$ from $t$ individual +signatures $\sigma_{i_k}$, $k=1,\dots,t$ and the Lagrange polynomials +$L_{i_1}, \dots,L_{i_t}$ associated to the set $I=\{i_1,\dots,i_t\}$ of signers. +``` + +### Better Emphasis + +The [Betterem extension](https://facelessuser.github.io/pymdown-extensions/extensions/betterem/) is +automatically applied to your bold and italic content. + +### Keyboard Shortcuts + +The [Keys syntax](https://facelessuser.github.io/pymdown-extensions/extensions/keys/) extension enables +displaying keyboard shortcuts. + +Example: +```markdown +++ctrl+C++ +``` + +### Folding Details Blocks + +You can use a folding block to hide content. The block can be closed by default or open. +This pattern helps reduce the content length and enables a faster overview of the whole page. + +Ex: +```markdown +???+ note "Folding details" + This is the detail of my content. + The plus sign makes it unfolded by default. + Remove the plus sign and it will be folded by default. +``` + +### Emojis + +Emojis are fun, but they can also be useful to draw the reader's attention. +Try to use only neutral emojis like :warning: + +Refer to a [supported full list of available emojis](https://www.webfx.com/tools/emoji-cheat-sheet/) +to find the suitable code. + +Example: +`:warning:` displays :warning: + +### Magic Links + +If you want an URL to be displayed as a link, simply write it and this extension automatically displays it as +a link. You don't need to surround it with Markdown links syntax. + +### Highlight Content + +The [Mark extension](https://facelessuser.github.io/pymdown-extensions/extensions/mark/) enables highlighting of +content. + +Text surrounded by double equals is highlighted in yellow. + +Example: +```markdown +==This is highlighted text== +``` + +### Strike Through + +The [tilde syntax](https://squidfunk.github.io/mkdocs-material/extensions/pymdown/#tilde) extensions enables text +strike through to be displayed. + +Example: +```markdown +~~This is the wrong way to do~~ +``` + +### Symbols + +The [Smart symbols syntax](https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/) enables +the inclusion of symbols. + +Ex: +`-->` will draw a nice right arrow. + +### Task lists + +The [Task list syntax](https://squidfunk.github.io/mkdocs-material/extensions/pymdown/#tasklist) extension +enables displaying a list as a checklist. + +### Code Samples And Examples With [SuperFences] + +#### Format The Code + +For writing code examples inside the documentation, refer to the developer style guides: + +- Java : refer to our [coding convention](CODING-CONVENTIONS.md). +- JSON : use https://jsonformatter.curiousconcept.com/ to format your JSON code. +- TOML : we follow version 0.5.0 language definition. +- JavaScript : see [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html). + +#### Including Code in the Documentation + +We use code-blocks provided by the [SuperFences] extension to present code samples and examples in the +documentation. + +A basic code-block uses triple back ticks and the language name to enable syntax highlighting. + +For example, a JSON result is written as: + +````markdown +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": true +} +``` +```` + +[SuperFences] enables additional functionality such as the tabbed code-block. + +For example, to group the usage syntax and a usage example in the same block with tabs: + +````markdown +```bash tab="Syntax" +$ pantheon rlp encode [--from=] [--to=] [--type=] +``` + +```bash tab="File Example" +$ pantheon rlp encode --from=ibft_extra_data.json --to=extra_data_for_ibft_genesis.txt --type=IBFT_EXTRA_DATA +``` + +```bash tab="Standart Input/Output Example" +$ cat extra_data.json | pantheon rlp encode > rlp.txt +``` +```` + +[SuperFences] also adds line numbers to the code sample which makes it easier when discussing the code the sample. + + +[MkDocs]: https://www.mkdocs.org/ +[readthedocs.org]: https://readthedocs.org/ +[Mkdocs Material]: https://squidfunk.github.io/mkdocs-material/ +[Gitter]: https://gitter.im/PegaSysEng/pantheon +[SuperFences]: https://squidfunk.github.io/mkdocs-material/extensions/pymdown/#superfences \ No newline at end of file diff --git a/docs/custom_theme/main.html b/docs/custom_theme/main.html index c639a7cfa9..70a91cc852 100644 --- a/docs/custom_theme/main.html +++ b/docs/custom_theme/main.html @@ -7,6 +7,7 @@ src="https://code.jquery.com/jquery-1.12.4.min.js" integrity="sha256-ZosEbRLbNQzLpnKIkEdrPv7lOy9C27hHQ+Xp8a4MxAQ=" crossorigin="anonymous"> + {% if config.extra.google.analytics_id %} diff --git a/mkdocs.yml b/mkdocs.yml index 514e681ea6..6647ca0c4e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -107,9 +107,7 @@ markdown_extensions: - pymdownx.arithmatex - pymdownx.betterem: smart_enable: all - - pymdownx.caret - pymdownx.keys - - pymdownx.critic - pymdownx.details - pymdownx.emoji - pymdownx.magiclink