Contributing guide

Welcome to pg_stat_monitor - the Query Performance Monitoring tool for PostgreSQL!

We're glad that you would like to become a Percona community member and participate in keeping open source open.

You can contribute in one of the following ways:

  1. Reach us on our Forums.
  2. Submit a bug report or a feature request
  3. Submit a pull request (PR) with the code patch
  4. Contribute to documentation

By contributing, you agree to the Percona Community code of conduct.

Submit a bug report or a feature request

All bug reports, enhancements and feature requests are tracked in Jira issue tracker. If you would like to suggest a new feature / an improvement or you found a bug in pg_stat_monitor, please submit the report to the PG project.

Start by searching the open tickets for a similar report. If you find that someone else has already reported your issue, then you can upvote that report to increase its visibility.

If there is no existing report, submit your report following these steps:

  1. Sign in to Jira issue tracker. You will need to create an account if you do not have one.
  2. In the Summary, Description, Steps To Reproduce, Affects Version fields describe the problem you have detected or an idea that you have for a new feature or improvement.

  3. As a general rule of thumb, try to create bug reports that are:

    • Reproducible: describe the steps to reproduce the problem.
    • Unique: check if there already exists a JIRA ticket to describe the problem.
    • Scoped to a Single Bug: only report one bug in one JIRA ticket

Submit a pull request

Though not mandatory, we encourage you to first check for a bug report among Jira issues and in the PR list: perhaps the bug has already been addressed.

For feature requests and enhancements, we do ask you to create a Jira issue, describe your idea and discuss the design with us. This way we align your ideas with our vision for the product development.

If the bug hasn’t been reported / addressed, or we’ve agreed on the enhancement implementation with you, do the following:

  1. Fork this repository
  2. Clone this repository on your machine.
  3. Create a separate branch for your changes. If you work on a Jira issue, please include the issue number in the branch name so it reads as <JIRAISSUE>-my_branch. This makes it easier to track your contribution.
  4. Make your changes. Please follow the guidelines outlined in the PostgreSQL Coding Standard to improve code readability.
  5. Test your changes locally. See the Running tests section for more information
  6. Update the documentation describing your changes. See the Contributing to documentation section for details

  7. Commit the changes. Add the Jira issue number at the beginning of your message subject, so that is reads as <JIRAISSUE> : My commit message. Follow this pattern for your commits:

    PG-1234: Main commit message. <Blank line> Details of fix.

    The commit message guidelines will help you with writing great commit messages

  8. Open a pull request to Percona

  9. Our team will review your code and if everything is correct, will merge it. Otherwise, we will contact you for additional information or with the request to make changes.
  10. Make sure your pull request contains only one commit message

Building pg_stat_monitor

To build pg_stat_monitor from source code, you require the following:

  • git
  • make
  • gcc
  • pg_config

Refer to the Building from source code section for guidelines.

Running tests

When you work, you should periodically run tests to check that your changes don’t break existing code.

You can find the tests in the regression directory.

Run manually

  1. Change directory to pg_stat_monitor

NOTE: Make sure postgres user is the owner of the pg_stat_monitor directory

  1. Start the tests

    1. If you built PostgreSQL from PGDG, use the following command:

      sh make installcheck

    2. If you installed PostgreSQL server from Percona Distribution for PostgreSQL, use the following command:

      sh sudo su postgres bash -c 'make installcheck USE_PGXS=1'

      Run automatically

The tests are run automatically with GitHub actions once you commit and push your changes. Make sure all tests are successfully passed before you proceed.

Contributing to documentation

pg_stat_monitor documentation is written in Markdown language, so you can edit it online via GitHub. Alternatively, you can include doc changes in your patch. The doc files are in the docs directory.

Edit documentation online via GitHub

  1. Click the Edit this page link on the sidebar. The source .md file of the page opens in GitHub editor in your browser. If you haven’t worked with the repository before, GitHub creates a fork of it for you.
  2. Edit the page. You can check your changes on the Preview tab.
  3. Commit your changes.
    • In the Commit changes section, describe your changes.
    • Select the Create a new branch for this commit and start a pull request option
    • Click Propose changes.
  4. GitHub creates a branch and a commit for your changes. It loads a new page on which you can open a pull request to Percona. The page shows the base branch - the one you offer your changes for, your commit message and a diff - a visual representation of your changes against the original page. This allows you to make a last-minute review. When you are ready, click the Create pull request button.
  5. Someone from our team reviews the pull request and if everything is correct, merges it into the documentation. Then it gets published on the site.

After your pull request is merged

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