Skip to content

Commit 89d106d

Browse files
AndriciucAndriciuc
authored
Update documentation contributing guide (14) (#916)
This PR updates the docs contributing guide with clearer instructions to submit issues through JIRA and GitHub for PPG 14.
1 parent 20f1be6 commit 89d106d

1 file changed

Lines changed: 72 additions & 112 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 72 additions & 112 deletions
Original file line numberDiff line numberDiff line change
@@ -1,201 +1,161 @@
1+
# Documentation contributing guide
12

2-
# Contributing Guide
3+
This guide explains how to contribute to the Percona Distribution for PostgreSQL documentation.
34

4-
Thank you for deciding to contribute and help us improve Percona Distribution for PostgreSQL documentation!
5+
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).
56

6-
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).
7+
If you want to contribute code, see the [Code contribution guide](https://github.com/percona/postgres/blob/PSP_REL_18_STABLE/.github/CONTRIBUTING.md).
78

8-
<<<<<<< HEAD
9-
This repository contains the source file for `pg_stat_monitor` documentation and this document explains how you can contribute to it.
10-
=======
119
You can contribute to documentation in the following ways:
1210

13-
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.
11+
1. Request documentation changes through Jira:
1412

15-
- 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.
16-
- Sign in (create a Jira account if you don’t have one) and click **Create** to create an issue.
17-
- Describe the issue you have detected in the Summary, Description, Steps To Reproduce, Affects Version fields.
13+
- Open the [Jira issue tracker](https://jira.percona.com/projects/PG/issues) for the project.
14+
- Sign in (create a Jira account if you don’t have one).
15+
- Click **Create** to create an issue.
16+
- (Optional but recommended) Search if the issue you want to report is already reported.
17+
- Select **PostgreSQL PG** in the Project dropdown and the work type.
18+
- Describe the issue in the Summary and Description fields. Optionally, you can also fill in the Steps To Reproduce and Affects Version fields.
1819

19-
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.
20-
>>>>>>> 9ee26788... Restructured docs
20+
2. [Contribute to documentation on GitHub](#contribute-directly-on-github).
2121

22-
## Contribute to documentation
22+
To contribute to the documentation, basic familiarity with the following tools is useful:
2323

24-
Percona Distribution for PostgreSQL documentation is written in [Markdown :octicons-link-external-16:](httpss://www.markdownguide.org/basic-syntax/) language, so you can
25-
[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).
24+
- [Markdown](https://www.markdownguide.org/basic-syntax/). The documentation is written in Markdown.
25+
- [MkDocs](https://www.mkdocs.org/getting-started/) documentation generator. We use it to convert source ``.md`` files to html and PDF documents.
26+
- [git](https://git-scm.com/) and [GitHub](https://guides.github.com/activities/hello-world/)
2627

27-
To contribute to the documentation, you should be familiar with the following technologies:
28-
<<<<<<< HEAD
28+
## Contribute directly on GitHub
2929

30-
- [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.
31-
- [git :octicons-link-external-16:](httpss://git-scm.com/) and [GitHub :octicons-link-external-16:](httpss://guides.github.com/activities/hello-world/)
32-
- [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.
33-
=======
34-
- [Markdown :octicons-link-external-16: :octicons-link-external-16:](httpss://www.markdownguide.org/basic-syntax/) markup language. It is used to write the documentation.
35-
- [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.
36-
- [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/)
37-
- [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.
38-
>>>>>>> 9ee26788... Restructured docs
30+
There are several active versions of the documentation. Each version derives from the major version of PostgreSQL, included in the distribution.
3931

40-
There are several active versions of the documentation. Each version derives from the major version of PostgreSQL, included in the distribution.
32+
Each documentation branch is named after the PostgreSQL major version (for example: `11`(EOL), `12`(EOL), `13`(EOL), `14`, `15`, `16`, `17`, `18`).
4133

42-
Each version has a branch in the repository named accordingly:
34+
The source .md files are in the ``postgresql-docs/docs`` directory.
4335

44-
- 11 (EOL)
45-
- 12 (EOL)
46-
- 13
47-
- 14
48-
- 15
49-
<<<<<<< HEAD
50-
=======
51-
- 16
52-
- 17
53-
>>>>>>> 5059c6e7... Tested a new PDF generation plugin
36+
To start contributing:
5437

55-
The source .md files are in the ``docs`` directory.
38+
1. Select **Edit this file**.
5639

57-
### Edit documentation online via GitHub
40+
> **NOTE**
41+
> 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.
5842
59-
<<<<<<< HEAD
60-
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.
61-
=======
62-
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.
63-
>>>>>>> 9ee26788... Restructured docs
64-
65-
2. Edit the page. You can check your changes on the **Preview** tab.
43+
2. Add your changes. You can see how your edit looks in the **Preview** tab.
6644

6745
3. Commit your changes.
6846

69-
- In the *Commit changes* section, describe your changes.
70-
- Select the **Create a new branch for this commit and start a pull request** option
71-
- Click **Propose changes**.
47+
- Describe the changes you have made
48+
- Select the **Create a new branch for this commit** and name your branch
49+
- Click **Propose changes** to create the pull request
7250

73-
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.
74-
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.
51+
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.
7552

76-
### Edit documentation locally
53+
5. Your changes will be reviewed and merged into the documentation.
7754

78-
This option is for users who prefer to work from their computer and / or have the full control over the documentation process.
55+
### Edit documentation locally
7956

80-
The steps are the following:
57+
If you want to work on your computer locally, follow these steps:
8158

8259
1. Fork this repository
8360
2. Clone the repository on your machine:
8461

8562
```sh
86-
git clone git@github.com:percona/postgresql-docs.git
63+
git clone git@github.com:<my_name>/postgresql-docs.git
64+
cd postgresql-docs
8765
```
8866

89-
3. Change the directory to ``postgresql-docs`` and add your local repository:
67+
3. Add the upstream (Percona) repository as a remote:
9068

9169
```sh
92-
git remote add <your-repo-name> git@github.com:<your_name>/postgresql-docs.git
70+
git remote add upstream git@github.com:percona/postgresql-docs.git
9371
```
9472

95-
4. Pull the latest changes
73+
4. Pull the latest changes
9674

9775
```sh
98-
git fetch origin
99-
git merge origin/<branch>
76+
git fetch upstream
77+
git merge upstream/<branch>
10078
```
10179

102-
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``.
80+
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``.
10381

104-
5. Create a separate branch for your changes
82+
5. Create a separate branch for your changes. If you work on a Jira issue, please follow this pattern for a branch name: `<PG-123>-short-description`:
10583

10684
```sh
107-
git checkout -b <my_changes>
85+
git checkout -b <PG-123>-short-description upstream/<target-branch>
10886
```
10987

110-
6. Make changes
111-
7. Commit your changes
112-
8. Open a pull request to Percona
113-
114-
### Building the documentation
115-
116-
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:
117-
118-
- [use Docker](#use-docker)
119-
- [install MkDocs and build locally](#install-mkdocs-and-build-locally)
120-
121-
Learn more about the documentation structure in the [Repository structure](#repository-stucture) section.
122-
123-
124-
#### Use Docker
125-
126-
1. [Get Docker :octicons-link-external-16: :octicons-link-external-16:](httpss://docs.docker.com/get-docker/)
127-
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:
88+
6. Make a commit mentioning the Jira issue in the commit message if any:
12889

12990
```sh
130-
docker run --rm -v $(pwd):/docs perconalab/pmm-doc-md mkdocs build
91+
git add .
92+
git commit -m "PG-123-<my_fixes>"
93+
git push -u origin <my_branch_name>
13194
```
13295

133-
If Docker can't find the image locally, it first downloads the image, and then runs it to build the documentation.
96+
7. Open a pull request to Percona
13497

135-
3. Go to the ``site`` directory and open the ``index.html`` file to see the documentation.
136-
4. To view your changes as you make them, run the following command:
98+
### Building the documentation using MkDocs
13799

138-
``` sh
139-
docker run --rm -p 8000:8000 -v $(pwd):/docs perconalab/pmm-doc-md mkdocs serve -a 0.0.0.0:8000
140-
```
100+
To verify how your changes look, generate the static site with the documentation. This process is called *building*.
141101

142-
5. To create a PDF version of the documentation, run the following command:
102+
> **NOTE**
103+
> Learn more about the documentation structure in the [Repository structure](#repository-structure) section.
143104
144-
```sh
145-
docker run --rm -v $(pwd):/docs perconalab/pmm-doc-md mkdocs build -f mkdocs-pdf.yml
146-
```
105+
To verify how your changes look, you can generate a static site locally:
147106

148-
The PDF document is in the ``site/pdf`` folder.
107+
1. Install [pip](https://pip.pypa.io/en/stable/installing/)
108+
2. Install [MkDocs](https://www.mkdocs.org/getting-started/#installation).
109+
3. Install all the required dependencies:
149110

150-
#### Install MkDocs and build locally
111+
```sh
112+
pip install -r requirements.txt
113+
```
151114

152-
1. Install [pip :octicons-link-external-16: :octicons-link-external-16:](httpss://pip.pypa.io/en/stable/installing/)
153-
2. Install [MkDocs :octicons-link-external-16: :octicons-link-external-16:](httpss://www.mkdocs.org/getting-started/#installation).
154-
3. While in the root directory of the doc project, run the following command to build the documentation:
115+
4. While in the root directory of the documentation project, run the following command to build the documentation:
155116

156117
```sh
157118
mkdocs build
158119
```
159-
4. Go to the ``site`` directory and open the ``index.html`` file in your web browser to see the documentation.
160-
5. To automatically rebuild the documentation and reload the browser as you make changes, run the following command:
120+
121+
5. Go to the ``site`` directory and open the ``index.html`` file in your web browser to see the documentation.
122+
6. To automatically rebuild the documentation and reload the browser as you make changes, run the following command:
161123

162124
```sh
163125
mkdocs serve
164126
```
165127

166-
6. To build the PDF documentation, do the following:
128+
You can also view the site at <http://127.0.0.1:8000>.
129+
130+
7. To build the PDF documentation, do the following:
167131
- Install [mkdocs-print-site-plugin](https://timvink.github.io/mkdocs-print-site-plugin/index.html)
168132
- Run the following command
169133

170134
```sh
171-
mkdocs build
135+
mkdocs build
172136
```
173137

174-
This creates a single HTML page for the whole doc project. You can find the page at `site/print_page.html`.
175-
176-
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.
177-
138+
This creates a single HTML page for the whole doc project. You can find the page at `site/print_page.html`.
178139

140+
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.
179141

180142
## Repository structure
181143

182144
The repository includes the following directories and files:
183145

184146
- `mkdocs-base.yml` - the base configuration file. It includes general settings and documentation structure.
185-
- `mkdocs.yml` - configuration file. Contains the settings for building the docs on Percona website
147+
- `mkdocs.yml` - configuration file. Contains the settings for building the documentation on Percona website
186148
- `docs`:
187149
- `*.md` - Source markdown files.
188150
- `_images` - Images, logos and favicons
189151
- `css` - Styles
190152
- `js` - Javascript files
191-
- `templates` - the PDF cover page template
192-
- `_resource`:
193-
- `overrides` - The directory with customized templates for HTML output
194-
- `main.html` - The layout template for hosting the documentation on Percona website
153+
- `templates`:
154+
- `pdf_cover_page.tpl` - The PDF cover page template
195155
- `_resourcepdf`:
196156
- `overrides` - The directory with customized layout templates for PDF
197157
- `.github`:
198158
- `workflows`:
199159
- `main.yml` - The workflow configuration for building documentation with a GitHub action. (The documentation is built with `mike` tool to a dedicated `publish` branch)
160+
- `snippets` - The folder with pieces of documentation used in multiple places
200161
- `site` - This is where the output HTML files are put after the build
201-
- `snippets` - The folder with pieces of documentation used in multiple places

0 commit comments

Comments
 (0)