Skip to content

Latest commit

 

History

History
187 lines (125 loc) · 9.36 KB

CONTRIBUTING.md

File metadata and controls

187 lines (125 loc) · 9.36 KB

Welcome to Percona Monitoring and Management (PMM)!

We're glad that you would like to become a Percona community member and participate in keeping open source open. Percona Monitoring and Management (PMM) is a open source database monitoring solution. It allows you to monitor your databases, different services (HAProxy, ProxySQL and etc) as well as Nodes, Kubernetes clusters and containers.

Table of contents

  1. Project repos structure
  2. API documentation
  3. Prerequisites
  4. Submitting a Bug
  5. Setup your local development environment
  6. Tests
  7. Feature Build
  8. Code Reviews

Project repos structure

This project is built from several repositories:

APIs

PMM Server

BackEnd

FrontEnd

PMM Client

Building and Packaging

QA, Testing and Documentation

API documentation

See API definitions here.

Prerequisites

Before submitting code or documentation contributions, you should first complete the following prerequisites.

1. Sign the CLA

Before you can contribute, we kindly ask you to sign our Contributor License Agreement (CLA). You can do this using your GitHub account and one click.

2. Code of Conduct

Please make sure to read and agree to our Code of Conduct.

Submitting a Bug

See Submitting Bug Reports in README.md.

Setup your local development environment

Since PMM has a lot of components, we will mention only three big parts of it.

PMM Server

  • Clone pmm-managed repository
  • Run make env-up to start development container.
  • To run pmm-managed with a new changes just run make env TARGET=run to update pmm-managed running in container.

PMM Client

  • Clone pmm-agent repository and pmm-admin repository.
  • Navigate to the root folder of pmm-agent.
  • Run make setup-dev to connect pmm-agent to PMM Server.
    • This command will register local pmm-agent to PMM Server and generate config file pmm-agent-dev.yaml
  • Once it's connected just use make run to run pmm-agent.
  • To work correctly pmm-agent needs exporters installed on the system.
    • All paths to exporters binaries are configured in pmm-agent-dev.yaml, so they can be changed manually
    • Exporters can be installed by building each of them or by downloading the pmm-client tarball from percona.com and copying binaries to the exporters_base directory configured in a pmm-agent-dev.yaml file.

Exporters

Exporters by themselves are independent applications, so each of them contains its own README files explaining how to set up a local environment see PMM Client.

UI

See Grafana Dashboards Contribution Guide.

Tests

In a PMM we have 4 kind of tests.

Unit tests

The first one is a Unit testing, so we have unit tests in each repository mentioned above. each of repositories has it's own instruction how to run unit tests.

API tests

API tests are included into pmm-managed repository and located in api-tests directory. API tests runs against running PMM Server container.

End to End (E2E) tests

End to End tests are located in pmm-qa repository. They includes UI tests and CLI tests. Please see readme for details on how to run theese.

Submitting a Pull Request

See Working with Git and GitHub

As a PR created you are responsible to:

  • make sure PR is ready (linted, tested and etc)
  • make sure it is reviewed (ask for review, ping reviewers and etc)
  • make sure it is merged
    • merge when it is reviewed and tested
    • ask code owners/admins to merge it if merging is blocked for some reason

Feature Build

PMM is quite complex project, it consists from many different repos descibed above. Feature Build (FB) is a way to get changes all together, build them all together, run tests and get client and server containers.

Please see: How to create a feature build

The Goals of the Feature Builds

  1. Provide an easy way to test/accept functionality for PO/PM and QA
  2. Inform the Developer about Automation Tests results before the code is merged
  3. (Future) Let the Developers add/modify e2e tests when they change functionality

The Rules

  1. Start Feature Build for every feature/improvement you are working on.
  2. Start PullRequest to percona-lab/pmm-submodules as DRAFT.
  3. Change the status of Pull Request from Draft to Open ONLY if your changes must be merged to pmm-submodules.
  4. Include a short explanation in the Long Description field of the Feature in PR for feature build and checkboxes to all related Pull Requests. Check other PRs as examples.
  5. After all related PRs in feature build are merged you should: a. either close the PR and delete the branch (this is the default option) or b. merge the PR to pmm-submodules repository (please note, this rarely needs to be merged, for example infrastructure changes do)

Code Reviews

There are number of approaches for the code review and ownership: Code Ownership (CODEOWNERS), github auto review, PR owner assign ppl that are better fit for the particular code/job.

For more efficient review process we use a mixed approach:

  • repos that have CODEOWNERS
    • add auto-review-team additionally to CODEOWNERS assigned
  • repos that don't have CODEOWNERS
    • add auto-review-team
  • if you know exactly who should review your code
    • add ppl to the review
Team Description Members
pmm-review-fe ppl for UI/UX reviews for FrontEnd repos FE team
pmm-review-exporters reviewers for all exporters see PMM Client Exporters team
pmm-review-be Back-End engineers BE team
PMM Admins ppl that could use admins rights to force merge or change repo settings PMM Admin team

After your Pull Request is merged

Once your pull request is merged, you are an official Percona Community Contributor. Welcome to the community!

We're looking forward to your contributions and hope to hear from you soon on our Forums and Discord.