diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7070fcc3..d4b1cfa6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,153 +1,131 @@ -# Contributing Guide +# 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). -You can contribute to documentation in the following ways: +If you want to contribute code, see the [Code contribution guide](https://github.com/percona/postgres/blob/PSP_REL_18_STABLE/.github/CONTRIBUTING.md). -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. +You can contribute to documentation in the following ways: - - 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. +1. Request documentation changes through Jira: -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. +- 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 on GitHub](#contribute-directly-on-github). -## Contribute to documentation yourself +To contribute to the documentation, basic familiarity with the following tools is useful: -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 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: +Each documentation branch is named after the PostgreSQL major version (for example: `11`(EOL), `12`(EOL), `13`(EOL), `14`, `15`, `16`, `17`, `18`). -- 11 (EOL) -- 12 (EOL) -- 13 (EOL) -- 14 -- 15 -- 16 -- 17 -- 18 +The source .md files are in the ``postgresql-docs/docs`` directory. -The source .md files are in the ``docs`` directory. +To start contributing: -### Edit documentation online via GitHub +1. Select **Edit this file**. -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 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 ```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 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](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: +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. - -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: -``` 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). 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: +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 @@ -155,17 +133,18 @@ mkdocs serve mkdocs build ``` -This creates a single HTML page for the whole doc project. You can find the page at `site/print_page.html`. +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. -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 - `docs`: - `*.md` - Source markdown files. - `_images` - Images, logos and favicons