From 3542d8a650c947b31eaba9eaff77d82ade51a7a0 Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Mon, 12 Jan 2026 18:56:18 +0200 Subject: [PATCH 1/5] Update Contributing Document This PR updates the contributing guide. --- CONTRIBUTING.md | 97 +++++++++++++++++++++---------------------------- 1 file changed, 42 insertions(+), 55 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7070fcc34..0d90885f5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,29 +1,33 @@ -# Contributing Guide +# Documentation contributing guide Thank you for deciding to contribute and help us improve Percona Distribution for PostgreSQL documentation! We welcome contributors from all users and community. By contributing, you agree to the [Percona Community code of conduct](https://github.com/percona/community/blob/main/content/contribute/coc.md). -You can contribute to documentation in the following ways: - -1. **Request a doc change through a Jira issue**. If you’ve spotted a doc issue (a typo, broken links, inaccurate instructions, etc.) but don’t have time nor desire to fix it yourself - let us know about it. +If you want to contribute code, see the [Code contribution guide](https://github.com/percona/postgres/blob/PSP_REL_18_STABLE/.github/CONTRIBUTING.md). - - Click the **Submit DOC bug** link on the sidebar. This opens the [Jira issue tracker](https://jira.percona.com/projects/PG/issues) for the doc project. - - Sign in (create a Jira account if you don’t have one) and click **Create** to create an issue. - - Describe the issue you have detected in the Summary, Description, Steps To Reproduce, Affects Version fields. +You can contribute to documentation in the following ways: -2. **[Contribute to documentation yourself](#contribute-to-documentation-yourself)**. Click the **Edit this page** icon that leads you to the source file of the page on GitHub. There you make changes, create a pull request that we review and add to the doc project. For details how to do it, read on. +1. Request a doc change through Jira: +- Open the [Jira issue tracker](https://jira.percona.com/projects/PG/issues) for the project. +- (Optional but recommended) Search if the issue you want to report is already reported. +- Sign in (create a Jira account if you don’t have one) and click **Create** to create an issue. +- Select **PostgreSQL PG** in the Project dropdown and the work type **Story**. +- Describe the issue you have detected in the Summary, Description, Steps To Reproduce and Affects Version fields. -## Contribute to documentation yourself +2. [Contribute to documentation on GitHub](#contribute-to-the-documentation-online-via-github). To contribute to the documentation, you should be familiar with the following technologies: -- [Markdown](https://www.markdownguide.org/basic-syntax/) markup language. It is used to write the documentation. + +- [Markdown](https://www.markdownguide.org/basic-syntax/). The documentation is written in Markdown. - [MkDocs](https://www.mkdocs.org/getting-started/) documentation generator. We use it to convert source ``.md`` files to html and PDF documents. - [git](https://git-scm.com/) and [GitHub](https://guides.github.com/activities/hello-world/) - [Docker](https://docs.docker.com/get-docker/). It allows you to run MkDocs in a virtual environment instead of installing it and its dependencies on your machine. -There are several active versions of the documentation. Each version derives from the major version of PostgreSQL, included in the distribution. +## Contribute to the documentation online via GitHub + +There are several active versions of the documentation. Each version derives from the major version of PostgreSQL, included in the distribution. Each version has a branch in the repository named accordingly: @@ -36,22 +40,26 @@ Each version has a branch in the repository named accordingly: - 17 - 18 -The source .md files are in the ``docs`` directory. +The source .md files are in the ``postgresql-docs/docs`` directory. + +To start contributing: -### Edit documentation online via GitHub +1. Click the **Edit this file** icon. -1. Click the **Edit this page** icon next to the page title. The Markdown file of the page opens in GitHub editor in your browser. If you haven’t worked with the repository before, GitHub creates a [fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) of it for you. +[!NOTE] +If you haven’t worked with the repository before, GitHub creates a [fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) of it for you. -2. Edit the page. You can check your changes on the **Preview** tab. +2. Add your changes. You can see how your edit looks like in 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**. +- Describe the changes you have made +- Select the **Create a new branch for this commit** and name your branch +- Click **Propose changes** to create the pull request -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. +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 changes. When you are ready, click the **Create pull request** button. + +5. Your changes will be reviewed and merged into the documentation. ### Edit documentation locally @@ -69,7 +77,7 @@ git clone git@github.com:percona/postgresql-docs.git 3. Change the directory to ``postgresql-docs`` and add your local repository: ```sh -git remote add git@github.com:/postgresql-docs.git +git remote add git@github.com:/postgresql-docs.git ``` 4. Pull the latest changes @@ -84,48 +92,27 @@ Make sure that your local branch and the branch you merge changes from are the s 5. Create a separate branch for your changes ```sh -git checkout -b +git checkout -b ``` -6. Make changes -7. Commit your changes -8. 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](#use-docker) -- [install MkDocs and build locally](#install-mkdocs-and-build-locally) - -Learn more about the documentation structure in the [Repository structure](#repository-stucture) section. - +6. Make a commit mentioning the Jira issue in the commit message if any: -#### Use Docker - -1. [Get Docker](https://docs.docker.com/get-docker/) -2. We use [this Docker image](https://github.com/Percona-Lab/percona-doc-docker) to build documentation. Run the following command: - -```sh -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. - -3. Go to the ``site`` directory and open the ``index.html`` file to see the documentation. -4. To view your changes as you make them, run the following command: + ``` + git add . + git commit -m "" + git push -u origin + ``` -``` sh -docker run --rm -p 8000:8000 -v $(pwd):/docs perconalab/pmm-doc-md mkdocs serve -a 0.0.0.0:8000 -``` +7. Open a pull request to Percona -5. To create a PDF version of the documentation, run the following command: +### Building the documentation using MkDocs -```sh -docker run --rm -v $(pwd):/docs -e ENABLE_PDF_EXPORT=1 perconalab/pmm-doc-md mkdocs build -f mkdocs-pdf.yml -``` +To verify how your changes look, generate the static site with the documentation. This process is called *building*. -The PDF document is in the ``site/pdf`` folder. +[!NOTE] +Learn more about the documentation structure in the [Repository structure](#repository-structure) section. -#### Install MkDocs and build locally +To verify how your changes look, you can generate a static site locally: 1. Install [pip](https://pip.pypa.io/en/stable/installing/) 2. Install [MkDocs](https://www.mkdocs.org/getting-started/#installation). From e539346491a42e92dcd6c6442695cc6b8a2bd4b9 Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Tue, 13 Jan 2026 12:54:44 +0200 Subject: [PATCH 2/5] Update to formatting, remove unnecessary information and clean the steps --- CONTRIBUTING.md | 90 ++++++++++++++++++++----------------------------- 1 file changed, 36 insertions(+), 54 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0d90885f5..65192d330 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,44 +1,34 @@ # Documentation contributing guide -Thank you for deciding to contribute and help us improve Percona Distribution for PostgreSQL documentation! +This guide explains how to contribute to the Percona Distribution for PostgreSQL documentation. -We welcome contributors from all users and community. By contributing, you agree to the [Percona Community code of conduct](https://github.com/percona/community/blob/main/content/contribute/coc.md). +We welcome contributors from all users and the community. By contributing, you agree to the [Percona Community code of conduct](https://github.com/percona/community/blob/main/content/contribute/coc.md). If you want to contribute code, see the [Code contribution guide](https://github.com/percona/postgres/blob/PSP_REL_18_STABLE/.github/CONTRIBUTING.md). You can contribute to documentation in the following ways: -1. Request a doc change through Jira: +1. Request documentation changes through Jira: - Open the [Jira issue tracker](https://jira.percona.com/projects/PG/issues) for the project. - (Optional but recommended) Search if the issue you want to report is already reported. - Sign in (create a Jira account if you don’t have one) and click **Create** to create an issue. -- Select **PostgreSQL PG** in the Project dropdown and the work type **Story**. -- Describe the issue you have detected in the Summary, Description, Steps To Reproduce and Affects Version fields. +- Select **PostgreSQL PG** in the Project dropdown and the work type. +- Describe the issue in the Summary and Description fields. Optionally, you can also fill in the Steps To Reproduce and Affects Version fields. -2. [Contribute to documentation on GitHub](#contribute-to-the-documentation-online-via-github). +2. [Contribute to documentation on GitHub](#contribute-directly-on-github). -To contribute to the documentation, you should be familiar with the following technologies: +To contribute to the documentation, basic familiarity with the following tools is useful: - [Markdown](https://www.markdownguide.org/basic-syntax/). The documentation is written in Markdown. - [MkDocs](https://www.mkdocs.org/getting-started/) documentation generator. We use it to convert source ``.md`` files to html and PDF documents. - [git](https://git-scm.com/) and [GitHub](https://guides.github.com/activities/hello-world/) -- [Docker](https://docs.docker.com/get-docker/). It allows you to run MkDocs in a virtual environment instead of installing it and its dependencies on your machine. -## Contribute to the documentation online via GitHub +## Contribute directly on GitHub There are several active versions of the documentation. Each version derives from the major version of PostgreSQL, included in the distribution. -Each version has a branch in the repository named accordingly: - -- 11 (EOL) -- 12 (EOL) -- 13 (EOL) -- 14 -- 15 -- 16 -- 17 -- 18 +Each documentation branch is named after the PostgreSQL major version (for example: `11`(EOL), `12`(EOL), `13`(EOL), `14`, `15`, `16`, `17`, `18`). The source .md files are in the ``postgresql-docs/docs`` directory. @@ -46,10 +36,10 @@ To start contributing: 1. Click the **Edit this file** icon. -[!NOTE] -If you haven’t worked with the repository before, GitHub creates a [fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) of it for you. +> **NOTE** +> If you haven’t worked with the repository before, GitHub creates a [fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) of it for you. -2. Add your changes. You can see how your edit looks like in the **Preview** tab. +2. Add your changes. You can see how your edit looks in the **Preview** tab. 3. Commit your changes. @@ -57,7 +47,7 @@ If you haven’t worked with the repository before, GitHub creates a [fork](http - Select the **Create a new branch for this commit** and name your branch - Click **Propose changes** to create the pull request -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 changes. When you are ready, click the **Create pull request** button. +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 last-minute changes. When you are ready, click the **Create pull request** button. 5. Your changes will be reviewed and merged into the documentation. @@ -71,37 +61,38 @@ The steps are the following: 2. Clone the repository on your machine: ```sh -git clone git@github.com:percona/postgresql-docs.git +git clone git@github.com:/postgresql-docs.git +cd postgresql-docs ``` 3. Change the directory to ``postgresql-docs`` and add your local repository: ```sh -git remote add git@github.com:/postgresql-docs.git +git remote add upstream git@github.com:percona/postgresql-docs.git ``` 4. Pull the latest changes ```sh -git fetch origin -git merge origin/ +git fetch upstream +git merge upstream/ ``` -Make sure that your local branch and the branch you merge changes from are the same. So if you are on the ``18`` branch, merge changes from ``origin/18``. +Make sure you merge changes from the same documentation branch you are working on. For example, if you are on branch ``18``, merge from ``upstream/18``. -5. Create a separate branch for your changes +5. Create a separate branch for your changes. If you work on a Jira issue, please follow this pattern for a branch name: `-short-description`: ```sh -git checkout -b +git checkout -b -short-description upstream/ ``` 6. Make a commit mentioning the Jira issue in the commit message if any: - ``` - git add . - git commit -m "" - git push -u origin - ``` +```sh +git add . +git commit -m "" +git push -u origin +``` 7. Open a pull request to Percona @@ -109,8 +100,8 @@ git checkout -b To verify how your changes look, generate the static site with the documentation. This process is called *building*. -[!NOTE] -Learn more about the documentation structure in the [Repository structure](#repository-structure) section. +> **NOTE** +> Learn more about the documentation structure in the [Repository structure](#repository-structure) section. To verify how your changes look, you can generate a static site locally: @@ -118,41 +109,32 @@ To verify how your changes look, you can generate a static site locally: 2. Install [MkDocs](https://www.mkdocs.org/getting-started/#installation). 3. Install all the required dependencies: -``` +```sh pip install -r requirements.txt ``` -3. While in the root directory of the doc project, run the following command to build the documentation: +4. While in the root directory of the documentation project, run the following command to build the documentation: ```sh mkdocs build ``` -4. Go to the ``site`` directory and open the ``index.html`` file in your web browser to see the documentation. -5. To automatically rebuild the documentation and reload the browser as you make changes, run the following command: + +5. Go to the ``site`` directory and open the ``index.html`` file in your web browser to see the documentation. +6. To automatically rebuild the documentation and reload the browser as you make changes, run the following command: ```sh mkdocs serve ``` -6. To build the PDF documentation, do the following: - - Install [mkdocs-print-site-plugin](https://timvink.github.io/mkdocs-print-site-plugin/index.html) - - Run the following command - - ```sh - mkdocs build - ``` - -This creates a single HTML page for the whole doc project. You can find the page at `site/print_page.html`. - -7. Open the `site/print_page.html` in your browser and save as PDF. Depending on the browser, you may need to select the Export to PDF, Print - Save as PDF or just Save and select PDF as the output format. +You can also view the site at . ## Repository structure The repository includes the following directories and files: - `mkdocs-base.yml` - the base configuration file. It includes general settings and documentation structure. -- `mkdocs.yml` - configuration file. Contains the settings for building the docs on Percona website -- `mkdocs-pdf.yml` - configuration file. Contains the settings for building the PDF docs. +- `mkdocs.yml` - configuration file. Contains the settings for building the documentation on Percona website +- `mkdocs-pdf.yml` - configuration file. Contains the settings for building the PDF documentation. - `docs`: - `*.md` - Source markdown files. - `_images` - Images, logos and favicons From 4f2d808651de7264b239803f75044a96b22e6f8b Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Wed, 14 Jan 2026 16:38:06 +0200 Subject: [PATCH 3/5] Update CONTRIBUTING.md Co-authored-by: Anastasia Alexandrova --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 65192d330..c73b3c0f1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -90,7 +90,7 @@ git checkout -b -short-description upstream/ ```sh git add . -git commit -m "" +git commit -m "PG-123-" git push -u origin ``` From dd4f916b2a0d881c644bd241bdb919a5c790ccf8 Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Wed, 14 Jan 2026 17:22:56 +0200 Subject: [PATCH 4/5] remove mkdocs pdf and split sign in and create in two steps --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c73b3c0f1..5be5244b1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,8 +11,9 @@ You can contribute to documentation in the following ways: 1. Request documentation changes through Jira: - Open the [Jira issue tracker](https://jira.percona.com/projects/PG/issues) for the project. +- Sign in (create a Jira account if you don’t have one). +- Click **Create** to create an issue. - (Optional but recommended) Search if the issue you want to report is already reported. -- Sign in (create a Jira account if you don’t have one) and click **Create** to create an issue. - Select **PostgreSQL PG** in the Project dropdown and the work type. - Describe the issue in the Summary and Description fields. Optionally, you can also fill in the Steps To Reproduce and Affects Version fields. @@ -134,7 +135,6 @@ The repository includes the following directories and files: - `mkdocs-base.yml` - the base configuration file. It includes general settings and documentation structure. - `mkdocs.yml` - configuration file. Contains the settings for building the documentation on Percona website -- `mkdocs-pdf.yml` - configuration file. Contains the settings for building the PDF documentation. - `docs`: - `*.md` - Source markdown files. - `_images` - Images, logos and favicons From 1deaf93e1a8ef68abcf3e4d1a129ce437a1b7472 Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Thu, 15 Jan 2026 12:42:53 +0200 Subject: [PATCH 5/5] Update CONTRIBUTING.md --- CONTRIBUTING.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5be5244b1..d4b1cfa6f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,7 +35,7 @@ The source .md files are in the ``postgresql-docs/docs`` directory. To start contributing: -1. Click the **Edit this file** icon. +1. Select **Edit this file**. > **NOTE** > If you haven’t worked with the repository before, GitHub creates a [fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) of it for you. @@ -54,9 +54,7 @@ To start contributing: ### 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: +If you want to work on your computer locally, follow these steps: 1. Fork this repository 2. Clone the repository on your machine: @@ -66,7 +64,7 @@ git clone git@github.com:/postgresql-docs.git cd postgresql-docs ``` -3. Change the directory to ``postgresql-docs`` and add your local repository: +3. Add the upstream (Percona) repository as a remote: ```sh git remote add upstream git@github.com:percona/postgresql-docs.git @@ -127,6 +125,18 @@ mkdocs build mkdocs serve ``` +7. To build the PDF documentation, do the following: + - Install [mkdocs-print-site-plugin](https://timvink.github.io/mkdocs-print-site-plugin/index.html) + - Run the following command + + ```sh + mkdocs build + ``` + +This creates a single HTML page for the whole doc project. You can find the page at `site/print_page.html`. + +8. Open the `site/print_page.html` in your browser and save as PDF. Depending on the browser, you may need to select the Export to PDF, Print - Save as PDF or just Save and select PDF as the output format. + You can also view the site at . ## Repository structure