Skip to content

Commit a55409b

Browse files
OffgridwithJDclaude
andcommitted
docs: point contributing guides at the GitHub project; require PostgreSQL coding standards
Rewrite CONTRIBUTING.md and documentation/docs/contribute.md for the standalone commandprompt/open_pg_tde project: - Replace the Percona Jira tracker with GitHub Issues, the Percona forums with GitHub Discussions, and "open a pull request to Percona" with pull requests against commandprompt/open_pg_tde. - Drop the Percona CLA and community references and the old contrib/open_pg_tde (percona/postgres) clone layout. - Update build/test and docs-build instructions for the standalone repo and upstream PostgreSQL 16+ (Material for MkDocs plugin set, meson test). Make the PostgreSQL coding conventions a firm, permanent requirement: all C code (extension and core patch) must satisfy https://www.postgresql.org/docs/current/source.html. Recorded in a new repo-root CLAUDE.md and called out in both contributing guides. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent e33868e commit a55409b

3 files changed

Lines changed: 131 additions & 223 deletions

File tree

CLAUDE.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# open_pg_tde project instructions
2+
3+
`open_pg_tde` is an open fork of Percona's `pg_tde`, maintained by Command Prompt, Inc.
4+
It provides Transparent Data Encryption for upstream PostgreSQL 16 and later.
5+
6+
## Coding standards (required)
7+
8+
All code in this project MUST satisfy the PostgreSQL coding conventions:
9+
https://www.postgresql.org/docs/current/source.html
10+
11+
This applies to every C change, in both the extension and the core patch under
12+
`patches/postgresql/`. Follow PostgreSQL's formatting, brace, naming,
13+
error-reporting (`ereport`/`errcode`), and memory-management (palloc/memory
14+
context) conventions, and run `pgindent` where applicable. Match the style of
15+
the surrounding PostgreSQL code. This is a firm requirement for every
16+
contribution and every review.
17+
18+
## How the project is built
19+
20+
- Runs on upstream PostgreSQL 16/17/18 (16 is the floor; the extension has no
21+
support below 16). It is NOT tied to a vendor server fork.
22+
- The core storage-manager and WAL extensibility is applied as a gated patch to
23+
a stock PostgreSQL source tree: `patches/postgresql/<major>/`, applied with
24+
`patches/postgresql/apply.sh`.
25+
- The patch is gated behind `USE_TDE_HOOKS` (`--enable-tde-hooks` /
26+
`-Dtde_hooks`). With the flag off, the patched tree builds as unmodified
27+
PostgreSQL. Verify both states with `patches/postgresql/verify-gate.sh`.
28+
- Docs are Material for MkDocs under `documentation/`.
29+
30+
## Documentation style
31+
32+
No em-dashes. Avoid unnecessary adjectives. Keep prose professional and factual.

CONTRIBUTING.md

Lines changed: 41 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,110 +1,94 @@
1-
# Code contributing guide
1+
# Contributing guide
22

3-
Welcome to `open_pg_tde` - the Transparent Database Encryption for PostgreSQL!
4-
5-
We're glad that you would like to become a Percona community member and participate in keeping open source open.
3+
Welcome to `open_pg_tde`, Transparent Data Encryption for PostgreSQL, maintained by Command Prompt, Inc.
64

75
You can contribute in one of the following ways:
86

9-
1. Reach us on our [Forums](https://forums.percona.com/c/postgresql/pg-tde-transparent-data-encryption-tde/82).
7+
1. [Start a discussion or ask a question](https://github.com/commandprompt/open_pg_tde/discussions)
108
2. [Submit a bug report or a feature request](#submit-a-bug-report-or-a-feature-request)
11-
3. [Submit a pull request (PR) with the code patch](#submit-a-pull-request)
12-
4. [Contribute to documentation](#documentation-contribution)
13-
14-
By contributing, you agree to the [Percona Community code of conduct](https://github.com/percona/community/blob/main/content/contribute/coc.md).
9+
3. [Submit a pull request (PR) with a code patch](#submit-a-pull-request)
10+
4. [Contribute to the documentation](#documentation-contribution)
1511

1612
## Submit a bug report or a feature request
1713

18-
All bug reports, enhancements and feature requests are tracked in [Jira issue tracker](https://jira.percona.com/projects/PG). If you would like to suggest a new feature / an improvement or you found a bug in `open_pg_tde`, please submit the report to the [PG project](https://jira.percona.com/projects/PG/issues).
14+
All bug reports, enhancements, and feature requests are tracked in [GitHub Issues](https://github.com/commandprompt/open_pg_tde/issues). If you found a bug, or you want to suggest a feature or an improvement, open an issue there.
1915

20-
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.
16+
Start by searching the open issues for a similar report. If someone has already reported it, add a reaction or a comment so we can gauge interest.
2117

22-
If there is no existing report, submit your report following these steps:
18+
If there is no existing report, open a new issue and aim for a report that is:
2319

24-
1. Sign in to [Jira issue tracker](https://jira.percona.com/projects/PG/issues). You will need to create an account if you do not have one.
25-
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.
26-
3. As a general rule of thumb, try to create bug reports that are:
20+
* Reproducible: describe the steps to reproduce the problem, including the PostgreSQL major version.
21+
* Unique: check that no existing issue already describes it.
22+
* Scoped to a single bug: report one bug per issue.
2723

28-
* Reproducible: describe the steps to reproduce the problem.
29-
* Unique: check if there already exists a JIRA ticket to describe the problem.
30-
* Scoped to a Single Bug: only report one bug in one JIRA ticket
24+
For feature requests and enhancements, open an issue that describes your idea so we can discuss the design before you start on a large change.
3125

3226
## Submit a pull request
3327

34-
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.
35-
36-
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.
28+
Before writing code, check the [open issues](https://github.com/commandprompt/open_pg_tde/issues) and [open pull requests](https://github.com/commandprompt/open_pg_tde/pulls) in case the change is already in progress.
3729

38-
If the bug hasn’t been reported / addressed, or we’ve agreed on the enhancement implementation with you, do the following:
30+
Then:
3931

40-
1. [Fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) this repository
32+
1. [Fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) this repository.
4133

42-
2. Clone this repository on your machine
34+
2. Clone your fork.
4335

44-
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`.
36+
3. Create a branch for your changes. If the change relates to an issue, include the issue number in the branch name, for example `123-encrypt-temp-files`.
4537

46-
4. Make your changes. Follow the guidelines outlined in the [PostgreSQL Coding Standard](https://www.postgresql.org/docs/current/source.html) to improve code readability.
38+
4. Make your changes. Follow the [PostgreSQL coding standards](https://www.postgresql.org/docs/current/source.html) for C code.
4739

48-
5. Test your changes locally. See the [Running tests](#running-tests) section for more information.
40+
5. Test your changes locally. See [Run tests](#run-tests).
4941

50-
6. To update the documentation describing your changes, see [Documentation contribution](#documentation-contribution).
42+
6. If your change needs documentation, see [Documentation contribution](#documentation-contribution).
5143

52-
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:
44+
7. Commit your changes with a clear message. If the change relates to an issue, reference it in the body, for example `Fixes #123`. Follow this pattern:
5345

5446
```
55-
PG-1234: Main commit message.
56-
<Blank line>
57-
Details of fix.
47+
Short summary of the change
48+
49+
Details of the change and why it is needed.
5850
```
5951
6052
See the [commit message guidelines](https://gist.github.com/robertpainsi/b632364184e70900af4ab688decf6f53) for more information.
6153
62-
8. Open a pull request to Percona
63-
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.
54+
8. Open a pull request against [`commandprompt/open_pg_tde`](https://github.com/commandprompt/open_pg_tde).
55+
56+
9. A maintainer will review your code. If everything is correct, we merge it. Otherwise, we will follow up with questions or requests for changes.
6457
6558
### Build open_pg_tde
6659
67-
To build `open_pg_tde` from source code, you require the following:
60+
`open_pg_tde` runs on upstream PostgreSQL 16 and later. You apply the `open_pg_tde` core patch to a PostgreSQL source tree, build it with the hooks enabled, and build the extension against that install.
61+
62+
To build from source you need:
6863
6964
* git
70-
* Meson
65+
* Meson and Ninja
7166
* gcc or clang
72-
* Percona Server for PostgreSQL 17 or later
67+
* OpenSSL development headers
7368
74-
Refer to the [Building from source code](https://github.com/commandprompt/open_pg_tde?tab=readme-ov-file#building-from-sources-for-community-postgresql) section for guidelines.
69+
See the [install from source guide](documentation/docs/install-from-source.md) for the full steps, and [`patches/postgresql/README.md`](patches/postgresql/README.md) for the core patch series and per-version status.
7570
7671
### Run tests
7772
78-
You can find the tests in the `sql` and `t` directories.
73+
The tests live in the `sql` and `t` directories.
7974
80-
#### Run manually
81-
82-
1. Change the directory to `open_pg_tde`
83-
84-
2. Build and install `open_pg_tde` with the following commands:
75+
1. Build and install the extension against your patched PostgreSQL:
8576
8677
```sh
8778
meson setup -Dpg_config=/path/to/postgresql/bin/pg_config ./build
88-
cd build
89-
meson install
79+
meson install -C ./build
9080
```
9181
92-
3. Start OpenKMIP
93-
94-
4. Run the tests using the following command:
82+
2. Run the suite:
9583
9684
```sh
97-
meson install && meson test --print-errorlogs
85+
meson test -C ./build --print-errorlogs
9886
```
9987
100-
#### Run automatically
88+
Some tests need a KMIP server or OpenBao; set `PG_TEST_REQUIRE_COSMIAN_KMS=1` or `PG_TEST_REQUIRE_OPENBAO=1` to require them. The frontend tools link against the server libraries, so set `LD_LIBRARY_PATH=/path/to/postgresql/lib` when running the suite.
10189
102-
The tests are run automatically with GitHub actions once you create a pull request.
90+
Tests also run automatically through GitHub Actions when you open a pull request.
10391
10492
## Documentation contribution
10593
106-
To contribute to the documentation, see the following [Documentation contribution guide](/documentation/documentation-contributing.md).
107-
108-
## After your pull request is merged
109-
110-
Once your pull request is merged, you are an official Percona Community Contributor. Welcome to the community!
94+
To contribute to the documentation, see the [documentation contributing guide](documentation/documentation-contributing.md).

0 commit comments

Comments
 (0)