open-dsi
/
postgres
mirror of https://github.com/postgres/postgres
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

PG-1355 Added the key points to consider when writing documentation (#52)

Browse Source 
PG-1355 Added the key points to consider when writing documentation

modified:   documentation/docs/contribute.md
modified:   contrib/pg_tde/documentation/CONTRIBUTING.md

---------

Co-authored-by: Zsolt Parragi <zsolt.parragi@percona.com>
Co-authored-by: Artem Gavrilov <artem.gavrilov@percona.com>
pull/209/head
Anastasia Alexandrova 7 months ago committed by GitHub
parent 3e3bbea82a
commit a6d39011f6
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 155 additions and 37 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 124
      contrib/pg_tde/documentation/CONTRIBUTING.md
  2. 64
      contrib/pg_tde/documentation/docs/contribute.md
  3. 4
      contrib/pg_tde/documentation/variables.yml

124
contrib/pg_tde/documentation/CONTRIBUTING.md
Unescape View File

@ -1,10 +1,90 @@
# 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:
1. Reach us on our [Forums](https://forums.percona.com/c/postgresql/25).
2. Submit a bug report or a feature request
3. Submit a pull request (PR) with the code patch
4. 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](https://cla-assistant.percona.com) (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](https://github.com/percona/community/blob/main/content/contribute/coc.md).
## Submitting a pull request
All bug reports, enhancements and feature requests are tracked in [Jira](https://perconadev.atlassian.net/jira/software/c/projects/PG/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 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](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) 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 follow this pattern for a branch name: `<PG-123>-name`. This makes it easier to track your contribution.
4. Make your changes. Please follow the following guidelines to improve code readability according to the order listed:
- [PostgreSQL coding conventions](https://www.postgresql.org/docs/current/source.html)
- [C style and Coding rules](https://github.com/MaJerle/c-code-style)
6. Write the documentation for your changes. See the [Write the docs](#write-the-docs) cheat sheet for details.
7. [Build the code](https://github.com/percona/postgres/wiki/Howtos) and [test your changes locally](#run-local-tests).
8. Commit the changes. The [commit message guidelines](https://gist.github.com/robertpainsi/b632364184e70900af4ab688decf6f53) will help you with writing great commit messages
9. Open a pull request to Percona.
10. Our team will review your code and documentation. 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:
```
source ci_scripts/setup-keyring-servers.sh
ci_scripts/make-test.sh
```
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](#edit-documentation-online-vi-github). If you wish to have more control over the doc process, jump to how to [edit documentation locally](#edit-documentation-locally).
`pg_tde` documentation is written in Markdown language, so you can [write the docs for your code changes](#write-the-docs) or
[edit the existing documentation online via GitHub](#edit-documentation-online-vi-github). If you wish to have more control over the doc process, jump to how to [edit documentation locally](#edit-documentation-locally).
Before you start, learn what [Markdown] is and how to write it. For your convenience, there's also a [Markdown cheat sheet] to help you with the syntax.
The doc files are in the `contrib/pg_tde/documentation/docs` directory.
### Write the docs
When you write code, make sure to write documentation that explains it for users. As the author, you know best how your code works. To explain your feature or improvement, use the following key points:
1. Feature Description: What is the feature about, and why does a user need it?
2. User Tasks: What tasks can a user solve with this feature?
3. Functionality: How does the feature work?
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](https://www.markdownguide.org/cheat-sheet/) to help you with the syntax.
4. Setup Requirements: How do you set it up? Are there any preconditions for it to work, such as existing setups or external configurations (e.g., what should be configured in a new Key Management Service - KMS)?
The doc files are in the `documentation` directory.
5. Setup Steps: What are the setup steps? Explain the commands and parameters used in functions. Give examples of using them. Provide sample outputs for commands.
6. Limitations and Breaking Changes: Are there any known limitations or breaking changes this feature introduces?
### Edit documentation online via GitHub
@ -27,26 +107,25 @@ The steps are the following:
2. Clone the repository on your machine:
```sh
git clone git@github.com:<your_name>/pg_tde.git
git clone --recursive git@github.com:<your-name>/postgres.git
```
3. Change the directory to ``pg_tde`` and add the remote upstream repository:
3. Change the directory to `contrib/pg_tde` and add the remote upstream repository:
```sh
git remote add upstream git@github.com:percona/pg_tde.git
git remote add upstream git@github.com:percona/postgres.git
```
4. Pull the latest changes from upstream
```sh
git fetch upstream
git merge upstream/main
```
5. Create a separate branch for your changes
```sh
git checkout -b <my_branch>
git checkout -b <PG-123-my_branch> upstream/TDE_REL_17_STABLE
```
6. Make changes
@ -58,7 +137,7 @@ git checkout -b <my_branch>
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](#use-docker)
- [Install MkDocs and build locally](#install-sphinx-and-build-locally)
- [Install MkDocs and build locally](#install-mkdocs-and-build-locally)
##### Use Docker
@ -66,7 +145,8 @@ To verify how your changes look, generate the static site with the documentation
2. We use [our Docker image](https://hub.docker.com/repository/docker/perconalab/pmm-doc-md) to build documentation. Run the following command:
```sh
docker run --rm -v $(pwd):/documentation perconalab/pmm-doc-md mkdocs build
cd contrib/pg_tde/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.
@ -75,7 +155,8 @@ docker run --rm -v $(pwd):/documentation perconalab/pmm-doc-md mkdocs build
If you want to see the changes as you edit the docs, use this command instead:
```sh
docker run --rm -v $(pwd):/documentation -p 8000:8000 perconalab/pmm-doc-md mkdocs serve --dev-addr=0.0.0.0:8000
cd contrib/pg_tde/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.
@ -93,6 +174,7 @@ Wait until you see `INFO - Start detecting changes`, then enter `0.0.0.0:800
3. Build the site:
```sh
cd contrib/pg_tde/documentation
mkdocs build
```
@ -101,11 +183,29 @@ Wait until you see `INFO - Start detecting changes`, then enter `0.0.0.0:800
Or, to run the built-in web server:
```sh
cd contrib/pg_tde/documentation
mkdocs serve
```
View the site at <http://127.0.0.1:8000>
#### Build PDF file
To build a PDF version of the documentation, do the following:
1. Disable displaying the last modification of the page:
```sh
export ENABLED_GIT_REVISION_DATE=false
```
2. Build the PDF file:
```sh
ENABLE_PDF_EXPORT=1 mkdocs build -f mkdocs-pdf.yml
```
View the site at <http://0.0.0.0:8000>
The PDF document is in the ``contrib/pg_tde/documentation/site/pdf`` folder.
[MkDocs]: https://www.mkdocs.org/
[Markdown]: https://daringfireball.net/projects/markdown/

64
contrib/pg_tde/documentation/docs/contribute.md
Unescape View File

@ -17,7 +17,7 @@ Before submitting code contributions, we ask you to complete the following prere
### 1. Sign the CLA
Before you can contribute, we kindly ask you to sign our [Contributor License Agreement](https://cla-assistant.percona.com/&lt;linktoCLA>) (CLA). You can do this in on click using your GitHub account.
Before you can contribute, we kindly ask you to sign our [Contributor License Agreement](https://cla-assistant.percona.com) (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.
@ -27,24 +27,25 @@ Please make sure to read and agree to our [Code of Conduct](https://github.com/p
## Submitting a pull request
All bug reports, enhancements and feature requests are tracked in [GitHub issues](https://github.com/percona/pg_tde/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.
All bug reports, enhancements and feature requests are tracked in [Jira](https://perconadev.atlassian.net/jira/software/c/projects/PG/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:
If the bug hasn't been reported / addressed, or we've agreed on the enhancement implementation with you, do the following:
1. [Fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) this repository
2. Clone this repository on your machine.
3. Create a separate branch for your changes. If you work on a GitHub issue, please [create a branch from it](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#manually-linking-a-pull-request-or-branch-to-an-issue-using-the-issue-sidebar). This makes it easier to track your contribution.
4. Make your changes. Please follow the following guidelines to improve code readability:
3. Create a separate branch for your changes. If you work on a Jira issue, please follow this pattern for a branch name: `<PG-123>-name`. This makes it easier to track your contribution.
4. Make your changes. Please follow the following guidelines to improve code readability according to the order listed:
- [PostgreSQL coding conventions](https://www.postgresql.org/docs/current/source.html)
- [C style and Coding rules](https://github.com/MaJerle/c-code-style)
5. [Build `pg_tde`](https://github.com/percona/pg_tde/wiki/Make-builds-for-developers) and [test your changes locally](#run-local-tests).
6. Commit the changes. The [commit message guidelines](https://gist.github.com/robertpainsi/b632364184e70900af4ab688decf6f53) will help you with writing great commit messages
7. Open a pull request to Percona.
8. Our team will review your code and if everything is correct, will merge it.
6. Write the documentation for your changes. See the [Write the docs](#write-the-docs) cheat sheet for details.
7. [Build the code](https://github.com/percona/postgres/wiki/Howtos) and [test your changes locally](#run-local-tests).
8. Commit the changes. The [commit message guidelines](https://gist.github.com/robertpainsi/b632364184e70900af4ab688decf6f53) will help you with writing great commit messages
9. Open a pull request to Percona.
10. Our team will review your code and documentation. 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
@ -54,20 +55,36 @@ When you work, you should periodically run tests to check that your changes don
To run the tests, use the following command:
```
cd pg_tde
make USE_PGXS=1 installcheck
source ci_scripts/setup-keyring-servers.sh
ci_scripts/make-test.sh
```
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](#edit-documentation-online-vi-github). If you wish to have more control over the doc process, jump to how to [edit documentation locally](#edit-documentation-locally).
`pg_tde` documentation is written in Markdown language, so you can [write the docs for your code changes](#write-the-docs) or
[edit the existing documentation online via GitHub](#edit-documentation-online-vi-github). If you wish to have more control over the doc process, jump to how to [edit documentation locally](#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.
Before you start, learn what [Markdown] is and how to write it. For your convenience, there's also a [Markdown cheat sheet] to help you with the syntax.
The doc files are in the `docs` directory.
The doc files are in the `documentation/docs` directory.
### Write the docs
When you write code, make sure to write documentation that explains it for users. As the author, you know best how your code works. To explain your feature or improvement, use the following key points:
1. Feature Description: What is the feature about, and why does a user need it?
2. User Tasks: What tasks can a user solve with this feature?
3. Functionality: How does the feature work?
4. Setup Requirements: How do you set it up? Are there any preconditions for it to work, such as existing setups or external configurations (e.g., what should be configured in a new Key Management Service - KMS)?
5. Setup Steps: What are the setup steps? Explain the commands and parameters used in functions. Give examples of using them. Provide sample outputs for commands.
6. Limitations and Breaking Changes: Are there any known limitations or breaking changes this feature introduces?
### Edit documentation online via GitHub
@ -90,25 +107,24 @@ The steps are the following:
2. Clone the repository on your machine:
```sh
git clone git@github.com:<your-name>/pg_tde.git
git clone --recursive git@github.com:<your-name>/postgres.git
3. Change the directory to ``pg_tde`` and add the remote upstream repository:
3. Change the directory to `contrib/pg_tde` and add the remote upstream repository:
```sh
git remote add upstream git@github.com:percona/pg_tde.git
git remote add upstream git@github.com:percona/postgres.git
```
4. Pull the latest changes from upstream
```sh
git fetch upstream
git merge upstream/main
```
5. Create a separate branch for your changes
```sh
git checkout -b <my_branch>
git checkout -b <PG-123-my_branch> upstream/{{tdebranch}}
```
6. Make changes
@ -128,7 +144,7 @@ To verify how your changes look, generate the static site with the documentation
2. We use [our Docker image](https://hub.docker.com/repository/docker/perconalab/pmm-doc-md) to build documentation. Run the following command:
```sh
cd documentation
cd contrib/pg_tde/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.
@ -138,7 +154,7 @@ docker run --rm -v $(pwd):/docs perconalab/pmm-doc-md mkdocs build
If you want to see the changes as you edit the docs, use this command instead:
```sh
cd documentation
cd contrib/pg_tde/documentation
docker run --rm -v $(pwd):/docs -p 8000:8000 perconalab/pmm-doc-md mkdocs serve --dev-addr=0.0.0.0:8000
```
@ -157,7 +173,7 @@ Wait until you see `INFO - Start detecting changes`, then enter `0.0.0.0:800
3. Build the site:
```sh
cd documentation
cd contrib/pg_tde/documentation
mkdocs build
```
@ -166,7 +182,7 @@ Wait until you see `INFO - Start detecting changes`, then enter `0.0.0.0:800
Or, to run the built-in web server:
```sh
cd documentation
cd contrib/pg_tde/documentation
mkdocs serve
```

4
contrib/pg_tde/documentation/variables.yml
Unescape View File

@ -1,4 +1,6 @@
#Variables used throughout the docs
release: 'Beta2'
pgversion17: '17.2'
pgversion17: '17.2'
tdebranch: TDE_REL_17_STABLE

Write Preview
Loading…
Cancel
Save