Have you read the Code of Conduct? By filing an Issue, you are expected to comply with it, including treating everyone with respect: https://github.com/PegasysEng/pantheon/blob/master/CODE-OF-CONDUCT.md
-->
### 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.
<!-- Thanks for sending a pull request! Here are some tips for you:
1. If this is your first time, read our contributor guidelines https://github.com/PegaSysEng/pantheon/blob/master/CONTRIBUTING.md#Your-First-Code-Contribution
4. Label the PR appropriately how to mark it: https://github.com/PegaSysEng/pantheon/blob/master/CONTRIBUTING.md#Pull-Request-Labels
-->
# PR Details
<!--- Provide a general summary of your changes in the Title above -->
## Description
<!--- Describe your changes in detail -->
**Which issue(s) this PR fixes** *(optional, in `fixes #<issue number>(, fixes #<issue_number>, ...)` format, will close the issue(s) when PR gets merged)*:
Fixes #
## Related Issue
<!--- This project only accepts pull requests related to open issues -->
<!--- If suggesting a new feature or change, please discuss it in an issue first -->
<!--- If fixing a bug, there should be an issue describing it with steps to reproduce -->
<!--- Please link to the issue here: -->
## Motivation and Context
<!--- Why is this change required? What problem does it solve? -->
## Types of changes
<!--- What types of changes does your code introduce? Put an `x` in all the boxes that apply: -->
- [ ] 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
<!-- Write your release note:
1. Enter your extended release note in the below block. If the PR requires additional action from users switching to the new release, include the string "action required".
2. If no release note is required, just write "NONE".
-->
```release-note
```
## Prerequisites:
<!--- Go over all the following points, and put an `x` in all the boxes that apply. -->
<!--- If you're unsure about any of these, don't hesitate to ask. We're here to help! -->
- [ ] 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
:+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)
[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 <details><summary>What if the status checks are failing?</summary>If a status check is failing, and you believe that the failure is unrelated to your change, please leave a comment on the pull request explaining why you believe the failure is unrelated. A maintainer will re-run the status check for you. If we conclude that the failure was a false positive, then we will open an issue to track that problem with our status check suite.</details>
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 |
| `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*).
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].
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:
- 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].
Eric Kellstrand
6 years ago
committed by
GitHub