From de9f71b199b22492b7c151ef4c6d5875bdd3e406 Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Mon, 19 Jan 2026 10:51:00 +0200 Subject: [PATCH] Update documentation contributing guide (14) This PR updates the docs contributing guide with clearer instructions to submit issues through JIRA and GitHub. --- CONTRIBUTING.md | 184 +++++++++++++++++++----------------------------- 1 file changed, 72 insertions(+), 112 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 09663dc42..2b78aad50 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,201 +1,161 @@ +# Documentation contributing guide -# Contributing Guide +This guide explains how to contribute to the Percona Distribution for PostgreSQL documentation. -Thank you for deciding to contribute and help us improve Percona Distribution for PostgreSQL documentation! +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). -We welcome contributors from all users and community. By contributing, you agree to the [Percona Community code of conduct :octicons-link-external-16: :octicons-link-external-16:](httpss://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). -<<<<<<< HEAD -This repository contains the source file for `pg_stat_monitor` documentation and this document explains how you can contribute to it. -======= 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. +1. Request documentation changes through Jira: - - Click the **Submit DOC bug** link on the sidebar. This opens the [Jira issue tracker :octicons-link-external-16: :octicons-link-external-16:](httpss://jira.percona.com/projects/DISTPG/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. +- 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. +- 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 yourself](#contribute-to-documentation-yourself)**. There is the **Edit this page** link 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. ->>>>>>> 9ee26788... Restructured docs +2. [Contribute to documentation on GitHub](#contribute-directly-on-github). -## Contribute to documentation +To contribute to the documentation, basic familiarity with the following tools is useful: -Percona Distribution for PostgreSQL documentation is written in [Markdown :octicons-link-external-16:](httpss://www.markdownguide.org/basic-syntax/) 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). +- [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/) -To contribute to the documentation, you should be familiar with the following technologies: -<<<<<<< HEAD +## Contribute directly on GitHub -- [MkDocs :octicons-link-external-16:](httpss://www.mkdocs.org/getting-started/) documentation generator. We use it to convert source ``.md`` files to .html and PDF documents. -- [git :octicons-link-external-16:](httpss://git-scm.com/) and [GitHub :octicons-link-external-16:](httpss://guides.github.com/activities/hello-world/) -- [Docker :octicons-link-external-16:](httpss://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. -======= -- [Markdown :octicons-link-external-16: :octicons-link-external-16:](httpss://www.markdownguide.org/basic-syntax/) markup language. It is used to write the documentation. -- [MkDocs :octicons-link-external-16: :octicons-link-external-16:](httpss://www.mkdocs.org/getting-started/) documentation generator. We use it to convert source ``.md`` files to html and PDF documents. -- [git :octicons-link-external-16: :octicons-link-external-16:](httpss://git-scm.com/) and [GitHub :octicons-link-external-16: :octicons-link-external-16:](httpss://guides.github.com/activities/hello-world/) -- [Docker :octicons-link-external-16: :octicons-link-external-16:](httpss://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. ->>>>>>> 9ee26788... Restructured docs +There are several active versions of the documentation. Each version derives from the major version of PostgreSQL, included in the distribution. -There are several active versions of the documentation. Each version derives from the major version of PostgreSQL, included in the distribution. +Each documentation branch is named after the PostgreSQL major version (for example: `11`(EOL), `12`(EOL), `13`(EOL), `14`, `15`, `16`, `17`, `18`). -Each version has a branch in the repository named accordingly: +The source .md files are in the ``postgresql-docs/docs`` directory. -- 11 (EOL) -- 12 (EOL) -- 13 -- 14 -- 15 -<<<<<<< HEAD -======= -- 16 -- 17 ->>>>>>> 5059c6e7... Tested a new PDF generation plugin +To start contributing: -The source .md files are in the ``docs`` directory. +1. Select **Edit this file**. -### Edit documentation online via GitHub +> **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. -<<<<<<< HEAD -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 :octicons-link-external-16:](httpss://docs.github.com/en/github/getting-started-with-github/fork-a-repo) of it for you. -======= -1. Click the **Edit this page** link on the sidebar. 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 :octicons-link-external-16: :octicons-link-external-16:](httpss://docs.github.com/en/github/getting-started-with-github/fork-a-repo) of it for you. ->>>>>>> 9ee26788... Restructured docs - -2. Edit the page. You can check your changes on the **Preview** tab. +2. Add your changes. You can see how your edit looks 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 last-minute changes. When you are ready, click the **Create pull request** button. -### Edit documentation locally +5. Your changes will be reviewed and merged into the documentation. -This option is for users who prefer to work from their computer and / or have the full control over the documentation process. +### Edit documentation locally -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: ```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: +3. Add the upstream (Percona) repository as a remote: ```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 +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 ``14`` branch, merge changes from ``origin/14``. +Make sure you merge changes from the same documentation branch you are working on. For example, if you are on branch ``14``, merge from ``upstream/14``. -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 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. - - -#### Use Docker - -1. [Get Docker :octicons-link-external-16: :octicons-link-external-16:](httpss://docs.docker.com/get-docker/) -2. We use [this Docker image :octicons-link-external-16: :octicons-link-external-16:](httpss://github.com/Percona-Lab/percona-doc-docker) to build documentation. Run the following command: +6. Make a commit mentioning the Jira issue in the commit message if any: ```sh -docker run --rm -v $(pwd):/docs perconalab/pmm-doc-md mkdocs build +git add . +git commit -m "PG-123-" +git push -u origin ``` - If Docker can't find the image locally, it first downloads the image, and then runs it to build the documentation. +7. Open a pull request to Percona -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: +### Building the documentation using MkDocs -``` sh -docker run --rm -p 8000:8000 -v $(pwd):/docs perconalab/pmm-doc-md mkdocs serve -a 0.0.0.0:8000 -``` +To verify how your changes look, generate the static site with the documentation. This process is called *building*. -5. To create a PDF version of the documentation, run the following command: +> **NOTE** +> Learn more about the documentation structure in the [Repository structure](#repository-structure) section. -```sh -docker run --rm -v $(pwd):/docs perconalab/pmm-doc-md mkdocs build -f mkdocs-pdf.yml -``` +To verify how your changes look, you can generate a static site locally: -The PDF document is in the ``site/pdf`` folder. +1. Install [pip](https://pip.pypa.io/en/stable/installing/) +2. Install [MkDocs](https://www.mkdocs.org/getting-started/#installation). +3. Install all the required dependencies: -#### Install MkDocs and build locally +```sh +pip install -r requirements.txt +``` -1. Install [pip :octicons-link-external-16: :octicons-link-external-16:](httpss://pip.pypa.io/en/stable/installing/) -2. Install [MkDocs :octicons-link-external-16: :octicons-link-external-16:](httpss://www.mkdocs.org/getting-started/#installation). -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: +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 + 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. +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 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.yml` - configuration file. Contains the settings for building the documentation on Percona website - `docs`: - `*.md` - Source markdown files. - `_images` - Images, logos and favicons - `css` - Styles - `js` - Javascript files - - `templates` - the PDF cover page template -- `_resource`: - - `overrides` - The directory with customized templates for HTML output - - `main.html` - The layout template for hosting the documentation on Percona website + - `templates`: + - `pdf_cover_page.tpl` - The PDF cover page template - `_resourcepdf`: - `overrides` - The directory with customized layout templates for PDF - `.github`: - `workflows`: - `main.yml` - The workflow configuration for building documentation with a GitHub action. (The documentation is built with `mike` tool to a dedicated `publish` branch) -- `site` - This is where the output HTML files are put after the build -- `snippets` - The folder with pieces of documentation used in multiple places \ No newline at end of file +- `snippets` - The folder with pieces of documentation used in multiple places +- `site` - This is where the output HTML files are put after the build \ No newline at end of file