Contributing guide¶

Welcome to pg_tde - the Transparent Data Encryption extension for PostgreSQL!

We’re glad that you would like to become a community member and contribute to this project.

You can contribute in one of the following ways:

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

Prerequisites¶

Before submitting code contributions, we ask you to 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 in on click using your GitHub account.

Note: You can sign it later, when submitting your first pull request. The CLA assistant validates the PR and asks you to sign the CLA to proceed.

2. Code of Conduct¶

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

Submitting a pull request¶

All bug reports, enhancements and feature requests are tracked in GitHub issues. Though not mandatory, we encourage you to first check for a bug report among the 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 GitHub 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:

Fork this repository
Clone this repository on your machine.
Create a separate branch for your changes. If you work on a GitHub issue, please create a branch from it. This makes it easier to track your contribution.
Make your changes. Please follow the following guidelines to improve code readability:
- PostgreSQL coding conventions
- C style and Coding rules
Build pg_tde and test your changes locally.
Commit the changes. The commit message guidelines will help you with writing great commit messages
Open a pull request to Percona.
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.

Run local tests¶

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

To run the tests, use the following command:

cd pg_tde
./configure
make USE_PGXS=1 installcheck

You can run tests on your local machine with whatever operating system you have. After you submit the pull request, we will check your patch on multiple operating systems.

Contribute to documentation¶

pg_tde documentation is written in Markdown language, so you can edit it online via GitHub. If you wish to have more control over the doc process, jump to how to edit documentation locally.

Before you start, learn what git, MkDocs and Docker are and what Markdown is and how to write it. For your convenience, there’s also a cheat sheet to help you with the syntax.

The doc files are in the docs directory.

Edit documentation online via GitHub¶

Click the Edit this page icon next to the page title. 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.
Edit the page. You can check your changes on the Preview tab.
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.
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.
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.

Edit documentation locally¶

This option is for users who prefer to work from their computer and / or have the full control over the documentation process.

The steps are the following:

Fork this repository
Clone the repository on your machine:

git clone git@github.com:<your-name>/pg_tde.git

3. Change the directory to ``pg_tde`` and add the remote upstream repository:

```sh
git remote add upstream git@github.com:percona/pg_tde.git

Pull the latest changes from upstream

git fetch upstream
git merge upstream/main

Create a separate branch for your changes

git checkout -b <my_branch>

Make changes
Commit your changes. The commit message guidelines will help you with writing great commit messages
Open a pull request to Percona

Building the documentation¶

To verify how your changes look, generate the static site with the documentation. This process is called building. You can do it in these ways: - Use Docker - Install MkDocs and build locally

Use Docker¶

Get Docker
We use our Docker image to build documentation. Run the following command:

cd documentation
docker run --rm -v $(pwd):/docs perconalab/pmm-doc-md mkdocs build

If Docker can’t find the image locally, it first downloads the image, and then runs it to build the documentation.

Go to the site directory and open the index.html file to see the documentation.

If you want to see the changes as you edit the docs, use this command instead:

cd documentation
docker run --rm -v $(pwd):/docs -p 8000:8000 perconalab/pmm-doc-md mkdocs serve --dev-addr=0.0.0.0:8000

Wait until you see INFO - Start detecting changes, then enter 0.0.0.0:8000 in the browser’s address bar. The documentation automatically reloads after you save the changes in source files.

Install MkDocs and build locally¶

Install Python.
Install MkDocs and required extensions:
```
pip install -r requirements.txt
```
Build the site:
```
cd documentation
mkdocs build
```
Open site/index.html

Or, to run the built-in web server:

cd documentation
mkdocs serve

View the site at http://0.0.0.0:8000

Build PDF file¶

To build a PDF version of the documentation, do the following:

Disable displaying the last modification of the page:
```
export ENABLED_GIT_REVISION_DATE=false
```
Build the PDF file:
```
ENABLE_PDF_EXPORT=1 mkdocs build -f mkdocs-pdf.yml
```
The PDF document is in the site/pdf folder.

Get expert help¶

If you need assistance, visit the community forum for comprehensive and free database knowledge, or contact our Percona Database Experts for professional support and services.

Community Forum Get a Percona Expert