-
Notifications
You must be signed in to change notification settings - Fork 135
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'main' into PMM-4879-mysql-add-defaults-file
- Loading branch information
Showing
82 changed files
with
9,936 additions
and
3,715 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,187 @@ | ||
| # 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)](https://www.percona.com/software/database-tools/percona-monitoring-and-management) 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](#Project-repos-structure) | ||
| 2. [API documentation](#API-documentation) | ||
| 3. [Prerequisites](#Prerequisites) | ||
| 4. [Submitting a Bug](#Submitting-a-Bug) | ||
| 5. [Setup your local development environment](#Setup-your-local-development-environment) | ||
| 6. [Tests](#Tests) | ||
| 7. [Feature Build](#Feature-Build) | ||
| 8. [Code Reviews](#Code-Reviews) | ||
|
|
||
| ## Project repos structure | ||
| This project is built from several repositories: | ||
|
|
||
| ### APIs | ||
|
|
||
| * [percona/pmm](https://github.com/percona/pmm) | ||
| * [percona-platform/saas](https://github.com/percona-platform/saas) | ||
| * [percona-platform/dbaas-api](https://github.com/percona-platform/dbaas-api) | ||
|
|
||
| ### PMM Server | ||
|
|
||
| #### BackEnd | ||
| * [percona/pmm-managed](https://github.com/percona/pmm-managed) | ||
| * [percona-platform/dbaas-controller](https://github.com/percona-platform/dbaas-controller) | ||
| * [percona/qan-api2](https://github.com/percona/qan-api2) | ||
| * [percona/pmm-update](https://github.com/percona/pmm-update) | ||
|
|
||
| #### FrontEnd | ||
| * [percona/grafana-dashboards](https://github.com/percona/grafana-dashboards) | ||
| * [percona-platform/grafana](https://github.com/percona-platform/grafana) | ||
|
|
||
| ### PMM Client | ||
|
|
||
| * [percona/pmm-agent](https://github.com/percona/pmm-agent) | ||
| * [percona/pmm-admin](https://github.com/percona/pmm-admin) | ||
| * [percona/node_exporter](https://github.com/percona/node_exporter) | ||
| * [percona/mysqld_exporter](https://github.com/percona/mysqld_exporter) | ||
| * [percona/mongodb_exporter](https://github.com/percona/mongodb_exporter) | ||
| * [percona/postgres_exporter](https://github.com/percona/postgres_exporter) | ||
| * [percona/proxysql_exporter](https://github.com/percona/proxysql_exporter) | ||
| * [percona/rds_exporter](https://github.com/percona/rds_exporter) | ||
| * [percona/azure_exporter](https://github.com/percona/azure_metrics_exporter) | ||
| * [Percona-Lab/clickhouse_exporter](https://github.com/Percona-Lab/clickhouse_exporter) | ||
| * [percona/percona-toolkit](https://github.com/percona/percona-toolkit) | ||
|
|
||
| ### Building and Packaging | ||
|
|
||
| * [percona/pmm-server](https://github.com/percona/pmm-server) | ||
| * [Percona-Lab/pmm-submodules](https://github.com/Percona-Lab/pmm-submodules) | ||
| * [Percona-Lab/jenkins-pipelines](https://github.com/Percona-Lab/jenkins-pipelines) | ||
|
|
||
| ### QA, Testing and Documentation | ||
| * [percona/pmm-ui-tests](https://github.com/percona/pmm-ui-tests) | ||
| * [percona/pmm-qa](https://github.com/percona/pmm-qa) | ||
| * [percona/pmm-doc](https://github.com/percona/pmm-doc) | ||
|
|
||
| ## API documentation | ||
|
|
||
| See API definitions [here](https://percona-pmm.readme.io/reference/introduction). | ||
|
|
||
| ## 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](https://cla-assistant.percona.com/<linktoCLA>) (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](https://github.com/percona/community/blob/main/content/contribute/coc.md). | ||
|
|
||
| ## Submitting a Bug | ||
|
|
||
| See [Submitting Bug Reports](README.md#Submitting-Bug-Reports) in [README.md](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](https://github.com/percona/pmm-managed) | ||
| * 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](https://github.com/percona/pmm-agent) and [pmm-admin repository](https://github.com/percona/pmm-admin). | ||
| * 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](https://www.percona.com/downloads/pmm2/) 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](#PMM-Client). | ||
|
|
||
| ### UI | ||
|
|
||
| See [Grafana Dashboards Contribution Guide](https://github.com/percona/grafana-dashboards/blob/main/CONTRIBUTING.md). | ||
|
|
||
| ## 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](https://github.com/percona/pmm-managed/tree/main/api-tests). API tests runs against running PMM Server container. | ||
|
|
||
| ### End to End (E2E) tests | ||
|
|
||
| End to End tests are located in [pmm-qa repository](https://github.com/percona/pmm-qa). They includes UI tests and CLI tests. | ||
| Please see [readme](https://github.com/percona/pmm-qa#readme) for details on how to run theese. | ||
|
|
||
| ## Submitting a Pull Request | ||
|
|
||
| See [Working with Git and GitHub](GIT_AND_GITHUB.md) | ||
|
|
||
| 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](https://github.com/Percona-Lab/pmm-submodules/blob/PMM-2.0/README.md#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](https://github.com/Percona-Lab/pmm-submodules/pulls) 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](https://docs.github.com/en/github/setting-up-and-managing-organizations-and-teams/managing-code-review-assignment-for-your-team), 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](#FrontEnd) | [FE team](https://github.com/orgs/percona/teams/pmm-review-fe/members) | | ||
| | pmm-review-exporters | reviewers for all exporters [see PMM Client](#PMM-Client) | [Exporters team](https://github.com/orgs/percona/teams/pmm-review-exporters/members) | | ||
| | pmm-review-be | Back-End engineers | [BE team](https://github.com/orgs/percona/teams/pmm-review-be/members) | | ||
| | PMM Admins | ppl that could use admins rights to force merge or change repo settings | [PMM Admin team](https://github.com/orgs/percona/teams/pmm-admins/members) | | ||
|
|
||
|
|
||
| ## 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](https://forums.percona.com) and [Discord](https://discord.gg/mQEyGPkNbR). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,66 @@ | ||
| # Working with Git and GitHub | ||
|
|
||
| The golden rule | ||
|
|
||
| Commit and push to the feature branches daily. Use pull requests (in the draft state until they are ready for review) to show WIP. Saying "I'm coding feature X" on the daily call without pushed commits is not okay. | ||
|
|
||
| ## Preparation | ||
|
|
||
| Make sure your `git user.name` is set, and `user.email` is set to your corporate (if you are Perconian) or personal email, i.e. [email protected]. | ||
|
|
||
| Use topic branches in the same repository instead of GitHub forks if you have such permissions. | ||
|
|
||
| Name topic branches like this: `PMM-1234-short-description`. Always start with `PMM-XXXX` or `SAAS-XXXX`. Never omit a short description. Separate words with dashes, not underscore. Use only lowercase letters. | ||
|
|
||
| If you are community contributor and there is no ticket exists, either create one or just use `short-description` style for your forked repo branch. | ||
|
|
||
| ## Commit rules | ||
|
|
||
| Every commit message should use this commit template: | ||
| ``` | ||
| PMM-XXXX Short summary up to 50 characters. | ||
| Optional 72-character wrapped longer description. | ||
| ``` | ||
|
|
||
| There should be a blank line between short summary and longer description. Final dot in the title is optional – if you hate it, drop it :) | ||
|
|
||
| While addressing review comments push the requested changes as a new commit instead of amending the original commit and force pushing to Github. | ||
|
|
||
| ## Pull Request rules | ||
|
|
||
| 1. Before Creating or updating PR always run linters and tests locally. | ||
| 2. Every PR should follow the template of a commit message. | ||
| 3. If PR provides a prototype or a proof-of-concept, PR should be draft so it is not accidentally merged. | ||
| 4. Start PR as draft ASAP to let everyone see the job you are doing. | ||
| 5. Check-list of things to do prior to submitting a PR for review: | ||
| - [x] All tests in the PR pass. | ||
| - [x] Clean up your code removing unnecessary tokens, code which is commented out, etc. | ||
| - [x] All required lint rules pass. | ||
| - [x] New tests are written if it's possible for new changes. | ||
| - [x] FB exists and is up-to-date. | ||
| - [x] All tests in FB pass. | ||
| - [x] Don't write unit tests that communicate with external services those tests belong in a separate API tests repo (This point might only be relevant to backend developers). | ||
| 6. Rules for merging a PR: | ||
| - [x] All required checks must pass. | ||
| - [x] The reviewers (minimum 2) are set as makes sense for the code (DevOps, BE, FE, QA), and all need to approve the code after review. | ||
| Should the person assigned as a reviewer not be able to review the PR in due time, they must un-assign themselves as a a reviewer of the said PR. | ||
| - [x] If change requests were made, all changes need to be resolved and re-approved by the original reviewers. | ||
| - [x] Task should have Ready for merge status | ||
| - [x] If all conditions for a successful merge are met (checks pass, code reviewed and approved, changes resolved and re-approved), ONLY then the PR can me merged: | ||
| * If a PR has Assignees, then the last approver should ping them in in the appropriate dev channel. Typically that means they want to merge several PRs in a feature build together. | ||
| * If a PR has no Assignees, then the last approver must assign it to the author and ping them on Slack. | ||
| * If required checks fail for a confusing reason or some non-required checks fail for a long time, ping the appropriate dev channel. | ||
| - [x] A PR should be merged with the "Squash and Merge" button (the code owner should set this as the only option in the repository settings). | ||
| - [x] Never leave PRs fully approved, unassigned, and not merged. | ||
| - [x] Tasks with several PRs should be merged with minimum time interval between the merges. | ||
| 7. Delete the branch after merging the PR (note: this step may be automated for some of our repos, i.e. a bot deletes the branch right after the merge). | ||
| 8. If you need to re-request a review from someone, please use GitHub feature as displayed in Figure 1 below (use case: I made some changes after the PR was reviewed so I want to request another review from the same reviewer). Ping reviewer if it's not reviewed in 1 working day. | ||
| 9. If you open a Pull Request to fix a Bug - put an explanation in the Long Description about the Bug. It may contain information about how it affects the component. Also, it's good to have short references on how the problem is solved (now applicable only to mongodb_exporter and proxysql_exporter) | ||
| 10. If you implement a new Feature or make an Improvement or Fix a Bug - add a link in the Long Description to the related PR for Feature Build. | ||
|
|
||
|
|
||
| [Check GitHub PR review documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review). | ||
|
|
||
| Figure 1. Request another review from a reviewer. | ||
|  |
Oops, something went wrong.