Skip to content

Commit c46d287

Browse files
nastena1606nastena1606
authored
DOCS-240 Updated the Contributing guide (#353)
* DOCS-240 Updated the Contributing guide
1 parent 09890bb commit c46d287

File tree

1 file changed

+153
-31
lines changed

1 file changed

+153
-31
lines changed

‎CONTRIBUTING.md‎

Lines changed: 153 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,63 +1,185 @@
11
# Contributing to Percona Operator for PostgreSQL documentation
22

3-
This repository contains the source file for Percona Operator for PostgreSQL documentation and this document explains how you can contribute to it.
3+
This repository contains the source files for Percona Operator for PostgreSQL documentation and this document explains how you can contribute to it.
44

5-
If you'd like to submit a code patch, follow the [Contributing guide in the Operator code repository](https://github.com/percona/percona-postgresql-operator/blob/main/CONTRIBUTING.md).
5+
If you'd like to submit a code patch, follow the [Contributing guide in the Operator code repository](https://github.com/percona/percona-postgresql-operator/blob/main/CONTRIBUTING.md).
66

7-
## Prerequisites
7+
By contributing, you agree to the [Percona Community code of conduct](https://github.com/percona/community/blob/main/content/contribute/coc.md).
88

9-
Before submitting code contributions, you should first complete the following prerequisites.
9+
The documentation is licensed under the [Attribution 4.0 International license (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/).
1010

11-
### 1. Sign the CLA
11+
## How to contribute
1212

13-
Before you can contribute, we kindly ask you to sign our [Contributor License Agreement](https://cla-assistant.io/percona/percona-postgresql-operator) (CLA). You can do this using your GitHub account and one click.
13+
You can contribute to documentation in the following ways:
1414

15-
### 2. Code of Conduct
15+
**1. Request a doc change through a Jira issue**
1616

17-
Please make sure to read and observe the [Contribution Policy](code-of-conduct.md).
17+
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.
1818

19-
## Submitting a pull request
19+
1. Open the [Jira issue tracker](https://jira.percona.com/projects/K8SPG/issues) in your browser.
20+
2. Sign in (create a Jira account if you don't have one).
21+
3. (Optional but recommended) Search if the issue you want to report is already reported.
22+
4. Click the [Create issue](https://perconadev.atlassian.net/secure/CreateIssue.jspa) shortcut to create an issue
23+
5. Select the Percona Operator for PostgreSQL in the Project dropdown and the issue type in the Issue Type dropdown. Click Next.
24+
6. Describe the issue you have detected in the Summary, Description, Steps To Reproduce, Affects Version fields.
25+
7. Click Create.
2026

21-
### 1. Making a bug report
27+
**2. Leave your feedback**
2228

23-
Improvement and bugfix tasks for Percona's projects are tracked in [Jira](https://jira.percona.com/projects/K8SPG/issues).
29+
We'd like to hear from you. Click **Rate this page** and leave your feedback. We will appreciate your leaving your email so that we can reach out to you with clarifications or updates, if needed.
2430

25-
Although not mandatory, it is a good practice to examine already open Jira issues first. For bigger contributions, we suggest creating a Jira issue and discussing it with the engineering team and community before proposing any code changes.
31+
**3. Contribute to documentation yourself**
2632

27-
Another good place to discuss Percona's projects with developers and other community members is the [community forum](https://forums.percona.com).
33+
## Contribute to documentation yourself
2834

29-
### 2. Contributing to the source tree
35+
Percona Operator for PostgreSQL documentation is written in [Markdown](https://www.markdownguide.org/basic-syntax/) language, so you can
36+
[edit it online via GitHub](#edit-documentation-online-via-github). If you wish to have more control over the doc process, jump to how to [edit documentation locally](#edit-documentation-locally).
3037

31-
Contributions to the source tree should follow the workflow described below:
38+
To contribute to the documentation, you should be familiar with the following technologies:
3239

33-
1. First, you need to [fork the repository on GitHub](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo), clone your fork locally, and then [sync your local fork to upstream](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/syncing-a-fork). After that, before starting to work on changes, make sure to always sync your fork with upstream.
34-
2. Create a branch for changes you are planning to make. If there is a Jira ticket related to your contribution, it is recommended to name your branch in the following way: `<Jira issue number>-<short description>`, where the issue number is something like `K8SPG-42`.
40+
- [MkDocs](https://www.mkdocs.org/getting-started/) documentation generator. We use it to convert source ``.md`` files to .html and PDF documents.
41+
- [git](https://git-scm.com/) and [GitHub](https://guides.github.com/activities/hello-world/)
42+
- [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.
43+
44+
The source `.md` files are in the `docs/` directory.
45+
46+
### Edit documentation online via GitHub
47+
48+
1. Click the **Edit this page** link on the sidebar. The source ``.md`` 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.
49+
50+
2. Edit the page. You can check your changes on the **Preview** tab.
51+
52+
3. Commit your changes.
53+
54+
- In the *Commit changes* section, describe your changes.
55+
- Select the **Create a new branch for this commit and start a pull request** option
56+
- Click **Propose changes**.
57+
58+
1. 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.
59+
2. 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.
60+
61+
### Edit documentation locally
62+
63+
This option is for users who prefer to work from their computer and / or have the full control over the documentation process.
64+
65+
The steps are the following:
66+
67+
1. [Fork this repository](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/syncing-a-fork)
68+
2. Clone the fork on your machine,
69+
3. Go to `k8spg-docs` and add the remote upstream repository:
70+
71+
```sh
72+
git remote add upstream git@github.com:percona/k8spg-docs.git
73+
```
74+
75+
4. Pull the latest changes from upstream
76+
77+
```sh
78+
git fetch upstream
79+
git merge upstream/main
80+
```
81+
82+
Always pull the latest changes before you start editing the documentation.
83+
84+
5. Create a branch for the changes you are planning to make. If there is a Jira ticket related to your contribution, name your branch in the following way: `<Jira issue number>-<short description>`, where the issue number is something like `K8SPG-372`.
3585

3686
Create the branch in your local repo as follows:
3787

3888
```
39-
$ git checkout -b K8SPG-42-fix-feature-X
89+
git checkout -b K8SPG-372-fix-feature-X
90+
```
91+
92+
6. When your changes are ready, make a commit, mentioning the Jira issue in the commit message, if any:
93+
94+
```
95+
git add .
96+
git commit -m "K8SPG-372 fixed by ......"
97+
git push -u origin K8SPG-372-fix-feature-X
4098
```
4199

42-
When your changes are ready, make a commit, mentioning the Jira issue in the commit message, if any:
100+
In the output you will see the link where to create a pull request.
101+
102+
Sample output:
43103

44104
```
45-
$ git add .
46-
$ git commit -m "K8SPG-42 fixed by ......"
47-
$ git push -u origin K8SPG-42-fix-feature-X
105+
remote: Create a pull request for 'K8SPG-372-fix-feature-X' on GitHub by visiting:
106+
remote: https://github.com/<your-name>/k8spg-docs/pull/new/K8SPG-372-fix-feature-X
48107
```
49108

50-
3. Create a pull request to the main repository on GitHub.
51-
4. When the reviewer makes some comments, address any feedback that comes and update the pull request.
52-
5. When your contribution is accepted, your pull request will be approved and merged to the main branch.
109+
7. Create a pull request on GitHub. 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.
110+
8. When the reviewer makes some comments, address any feedback that comes and update the pull request. Read more about the process in the [code review](#code-review).
111+
9. When your contribution is accepted, your pull request will be approved and merged to the main branch.
112+
113+
#### Code review
114+
115+
Your contribution will be reviewed by other developers contributing to the project. The more complex your changes are, the more experts will be involved. You will receive feedback and recommendations directly on your pull request on GitHub, so keep an eye on your submission and be prepared to make further amendments. The developers might even provide some concrete suggestions on how to modify your code to better match the project’s expectations.
116+
117+
### Building the documentation
118+
119+
To verify how your changes look, generate the static site with the documentation. This process is called *building*.
120+
121+
#### Preconditions
122+
123+
1. Install [Python].
124+
125+
2. Install MkDocs and required extensions:
126+
127+
```sh
128+
pip install -r requirements.txt
129+
```
130+
131+
#### Build the site
132+
133+
1. To build the site, run:
134+
135+
```sh
136+
mkdocs build
137+
```
138+
139+
2. Open `site/index.html`
140+
141+
#### Live preview
142+
143+
To view your changes as you make them, run the following command:
144+
145+
```sh
146+
mkdocs serve
147+
```
148+
149+
Paste the <http://127.0.0.1:8000> in your browser and you will see the documentation. The page reloads automatically as you make changes.
150+
151+
#### PDF
152+
153+
To build the PDF documentation, open the `site/print_page.html` in your browser. Save it 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.
154+
155+
## After your pull request is merged
53156

54-
### 3. Contributing to documentation
157+
Once your pull request is merged, you are an official Percona Community Contributor. Welcome to the community!
55158

56-
Please take into account a few things:
159+
## Repository structure
57160

58-
1. All documentation is written using the [Markdown markup language](https://en.wikipedia.org/wiki/Markdown). It allows easy publishing of various output formats such as HTML and PDF.
59-
2. We store the documentation as *.md files in the [main](https://github.com/percona/k8spg-docs/tree/main) branch of the repository and use [MkDocs](https://www.mkdocs.org/) to convert Markdown files into a static HTML website or PDF. The documentation is licensed under the [Attribution 4.0 International license (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/).
161+
The repository includes the following directories and files:
60162

61-
## Code review
163+
- `mkdocs-base.yml` - the base configuration file. It includes general settings and documentation structure.
164+
- `mkdocs.yml` - configuration file. Contains the settings for building the docs with Material theme.
165+
- `docs`:
166+
- `*.md` - Source markdown files.
167+
- `assets` - Images, text snippets and templates
168+
- `images` - Images, logos and favicons
169+
- `code` - Examples of reusable command outputs
170+
- `fragments` - Text snippets used in multiple places in docs.
171+
- `templates`:
172+
- `pdf_cover_page.tpl` - The PDF cover page template
173+
- `css` - Styles
174+
- `js` - Javascript files
175+
- `fonts` - Custom fonts
176+
- `_resource`: The set of Material theme templates with our customizations
177+
- `.icons` - Custom icons used in the documentation
178+
- `overrides`:
179+
- `partials` - The layout templates for various parts of the documentation such as header, copyright and others.
180+
- `main.html` - The layout template for hosting the documentation on Percona website
181+
- `404.html` - The 404 page template
182+
- `_resourcepdf` - The set of Material theme templates with our customizations for PDF builds
183+
- `site` - This is where the output HTML files are put after the build
62184

63-
Your contribution will be reviewed by other developers contributing to the project. The more complex your changes are, the more experts will be involved. You will receive feedback and recommendations directly on your pull request on GitHub, so keep an eye on your submission and be prepared to make further amendments. The developers might even provide some concrete suggestions on modifying your code to match the project’s expectations better.
185+
[Python]: https://www.python.org/downloads/

0 commit comments

Comments
 (0)