|
1 | | -# Code contributing guide |
| 1 | +# Contributing guide |
2 | 2 |
|
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. |
6 | 4 |
|
7 | 5 | You can contribute in one of the following ways: |
8 | 6 |
|
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) |
10 | 8 | 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) |
15 | 11 |
|
16 | 12 | ## Submit a bug report or a feature request |
17 | 13 |
|
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. |
19 | 15 |
|
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. |
21 | 17 |
|
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: |
23 | 19 |
|
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. |
27 | 23 |
|
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. |
31 | 25 |
|
32 | 26 | ## Submit a pull request |
33 | 27 |
|
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. |
37 | 29 |
|
38 | | -If the bug hasn’t been reported / addressed, or we’ve agreed on the enhancement implementation with you, do the following: |
| 30 | +Then: |
39 | 31 |
|
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. |
41 | 33 |
|
42 | | -2. Clone this repository on your machine |
| 34 | +2. Clone your fork. |
43 | 35 |
|
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`. |
45 | 37 |
|
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. |
47 | 39 |
|
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). |
49 | 41 |
|
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). |
51 | 43 |
|
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: |
53 | 45 |
|
54 | 46 | ``` |
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. |
58 | 50 | ``` |
59 | 51 |
|
60 | 52 | See the [commit message guidelines](https://gist.github.com/robertpainsi/b632364184e70900af4ab688decf6f53) for more information. |
61 | 53 |
|
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. |
64 | 57 |
|
65 | 58 | ### Build open_pg_tde |
66 | 59 |
|
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: |
68 | 63 |
|
69 | 64 | * git |
70 | | -* Meson |
| 65 | +* Meson and Ninja |
71 | 66 | * gcc or clang |
72 | | -* Percona Server for PostgreSQL 17 or later |
| 67 | +* OpenSSL development headers |
73 | 68 |
|
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. |
75 | 70 |
|
76 | 71 | ### Run tests |
77 | 72 |
|
78 | | -You can find the tests in the `sql` and `t` directories. |
| 73 | +The tests live in the `sql` and `t` directories. |
79 | 74 |
|
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: |
85 | 76 |
|
86 | 77 | ```sh |
87 | 78 | meson setup -Dpg_config=/path/to/postgresql/bin/pg_config ./build |
88 | | - cd build |
89 | | - meson install |
| 79 | + meson install -C ./build |
90 | 80 | ``` |
91 | 81 |
|
92 | | -3. Start OpenKMIP |
93 | | -
|
94 | | -4. Run the tests using the following command: |
| 82 | +2. Run the suite: |
95 | 83 |
|
96 | 84 | ```sh |
97 | | - meson install && meson test --print-errorlogs |
| 85 | + meson test -C ./build --print-errorlogs |
98 | 86 | ``` |
99 | 87 |
|
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. |
101 | 89 |
|
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. |
103 | 91 |
|
104 | 92 | ## Documentation contribution |
105 | 93 |
|
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