You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
We welcome contributions from all users and the community. By contributing, you agree to the [Percona Community code of conduct](https://percona.community/contribute/coc/). Thank you for deciding to contribute and help us improve the [Percona Server documentation](https://docs.percona.com/percona-server/).
3
+
We welcome contributions from all users and the community. By contributing, you agree to the [Percona Community code of conduct](https://percona.community/contribute/coc/). Thank you for deciding to contribute and help us improve the [Percona Server for MySQL documentation](https://docs.percona.com/percona-server/).
4
4
5
-
You can contribute to the documentation in either of the following ways:
5
+
You can contribute to the documentation in one of the following ways:
-[Building the documentation](#building-the-documentation)
7
+
***Forum**: Best for questions, discussions, or general feedback
16
8
17
-
## Add a topic
9
+
***Jira ticket**: Best for reporting issues or requesting changes that you'd like the team to handle
18
10
19
-
In the [Percona Product Documentation category](https://forums.percona.com/c/percona-product-documentation/71) in the Percona Community Forum, select **New Topic**. Complete the form and select **Create Topic** to add the topic to the forum.
11
+
***Edit yourself**: Best for making direct changes, fixing typos, or adding content
12
+
13
+
## Add a topic in the Percona Community Forum
14
+
15
+
The [Percona Community Forum](https://forums.percona.com/) is a public discussion platform where you can ask questions, share feedback, or suggest improvements to the documentation. Use the forum to start a conversation about documentation issues, request clarifications, or discuss potential changes with the community and documentation team.
16
+
17
+
To add a topic, navigate to the [Percona Product Documentation category](https://forums.percona.com/c/percona-product-documentation/71) in the Percona Community Forum and select **New Topic**. Complete the form and select **Create Topic** to add the topic to the forum.
20
18
21
19
![Create a topic](docs/_static/new-topic.png"Create a topic")
22
20
23
21
## Request a change with a Jira issue
24
22
25
-
If you would rather not [contribute to the documentation yourself](#contribute-to-documentation-yourself), let us know about the issue by adding a Jira ticket. Use the following procedure to create a Jira ticket:
23
+
You can report documentation issues or request changes by creating a Jira ticket. This method is useful when you want to track the issue formally or when you want the documentation team to handle the changes.
24
+
25
+
Use the following procedure to create a Jira ticket:
26
+
27
+
1. Open the [Percona Server Jira project](https://jira.percona.com/projects/PS/issues) in your browser.
28
+
29
+
2. Sign in (or create a Percona Jira account if you don't have one).
30
+
31
+
3. Click the **Create** button.
32
+
33
+
4. Fill in the required fields:
26
34
27
-
In the Contact Us section, select the link in "open a JIRA ticket"
35
+
***Summary**: Provide a brief description of the issue.
***Description**: Provide more information about the issue. If needed, add a Steps To Reproduce section and information about your environment (version number, your operating system, etc.). Be detailed.
30
38
31
-
- In the `Contact Us` section, located at the bottom of the page, select the **open a JIRA ticket** link. This action opens the [Jira issue tracker](https://jira.percona.com/projects/PS/issues) for the doc project.
39
+
***Version**, **Environment**, and other relevant fields as needed.
32
40
33
-
- Log in (create a Jira account if you don't have one) and select **Create** to open the Jira form.
41
+
5. Click **Create** to submit the ticket.
34
42
35
-
![Complete the Jira form](docs/_static/create-issue.png"Complete the Jira form")
43
+
!!! tip "Shortcut to the issue creation screen"
36
44
37
-
- In the following fields, describe the issue:
38
-
- In the Summary, provide a brief description of the issue.
39
-
- In the Description, provide more information about the issue. If needed, add a Steps To Reproduce section and information about your environment (version number, your operating system, etc.). Be detailed.
40
-
- Select **CREATE** to create the ticket.
45
+
To go directly to the Create Issue form, use this URL: [https://jira.percona.com/secure/CreateIssue!default.jspa?pid=10100](https://jira.percona.com/secure/CreateIssue!default.jspa?pid=10100)
41
46
42
-
## Contribute to documentation yourself
47
+
## Edit documentation yourself
43
48
44
-
Use either the [Edit documentation online with GitHub](#edit-documentation-online-with-github) method or the [Edit documentation locally](#edit-documentation-locally) method to make changes to the documentation and create a pull request.
49
+
Use the [Edit documentation online with GitHub](#edit-documentation-online-with-github) method or the [Edit documentation locally](#edit-documentation-locally) method to make changes to the documentation and create a pull request.
45
50
46
51
### What you should know
47
52
48
-
Most of the document is in plain text, but you may use [Markdown](https://www.markdownguide.org/) to add syntax elements (notes, tables, and so on) to the documentation.
53
+
Most of the documentation is in plain text, but you may use [Markdown](https://www.markdownguide.org/) to add syntax elements (notes, tables, and so on) to the documentation.
49
54
50
55
### What happens after you create the pull request
51
56
52
-
A core developer reviews your request and either comments or approves the request. A core developer merges the approved request to the **main** branch usually when a newer version of the product is released.
57
+
Our team reviews your pull request and provides feedback or approval. Once approved, we merge your changes into the appropriate branch. Thank you for taking the time to improve our documentation!
53
58
54
59
!!! note
55
60
56
-
We appreciate your work but the pull request may be redone to meet internal requirements.
61
+
We appreciate your work, but the PR may be revised to meet internal requirements.
57
62
58
63
### Edit documentation online with GitHub
59
64
60
-
Next to the page title, select the pencil icon to open the source file in the GitHub editor. In this editor, you can make the changes, view the changes in the Preview tab, and create a pull request. The source `.md` file of the page opens in a 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).
65
+
1.Next to the page title, select **Edit this page on GitHub**to open the source file in the GitHub editor. 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) automatically.
61
66
62
-
Edit the page using the [Markdown](https://www.markdownguide.org/) syntax.
67
+
2.Edit the page using the [Markdown](https://www.markdownguide.org/) syntax.
63
68
64
-
You should review your changes on the **Preview** tab.
69
+
3. Review your changes by clicking the **Preview** tab to see how they will appear.
65
70
66
-
Commit your changes to a pull request.
71
+
4. Scroll to the bottom of the page to the **Commit changes** section.
67
72
68
-
In the **Commit changes** section, add a summary (72 characters or less) of what was changed.
69
-
70
-
Then select the **Create a new branch for this commit and start a pull request** option. Accept the name for the branch and then Select **Commit changes**.
73
+
5. Add a commit message (72 characters or less) describing what you changed.
71
74
72
-
GitHub creates a branch and a commit for your changes. The operation loads a page that shows the following:
75
+
6. Select the **Create a new branch for this commit and start a pull request** option. GitHub will suggest a branch name, which you can accept or modify.
73
76
74
-
- a base branch where you offer your changes
75
-
76
-
- your commit message
77
-
78
-
- a visual representation of your changes against the original page
77
+
7. Click **Commit changes**.
79
78
80
-
Review the information and click **Create pull request**.
79
+
8. GitHub creates a branch and commit for your changes, then displays a page where you can create a pull request. This page shows:
81
80
82
-
For more information, see [Editing files in GitHub](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files)
81
+
* The base branch where you're proposing your changes
82
+
83
+
* Your commit message
84
+
85
+
* A visual diff of your changes
86
+
87
+
9. Review the information and click **Create pull request**.
88
+
89
+
For more information, see [Editing files in GitHub](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files).
83
90
84
91
### Edit documentation locally
85
92
86
-
This option is for users who are comfortable with [git](https://git-scm.com/) commands.
93
+
This option is for users who are comfortable with [git](https://git-scm.com/) commands.
4. Checkout the appropriate branch and pull the latest changes from origin:
116
+
4. Checkout the main branch and pull the latest changes from upstream:
106
117
107
118
```shell
108
-
git checkout main && git pull origin main
119
+
git checkout main
120
+
git pull upstream main
109
121
```
110
122
111
123
5. Create a separate branch for your changes:
@@ -114,68 +126,74 @@ The steps are the following:
114
126
git checkout -b <my_changes>
115
127
```
116
128
117
-
6. Workin the `/docs` directory. Add code examples, if necessary. We recommend that you check your changes using either a Preview built into your editor (if you have one) or [build HTML on your machine](#building-the-documentation).
129
+
6. Edit the filesin the `/docs` directory. Add code examples, if necessary. We recommend that you check your changes using either a Preview built into your editor (if you have one) or [build HTML on your machine](#building-the-documentation).
118
130
119
-
7. Add the changed file:
131
+
7. Add the changed file (replace `docs/example.md` with your actual file path):
120
132
121
133
```shell
122
-
git add <changed file>
134
+
git add docs/example.md
123
135
```
124
136
125
-
8. Commit your changes:
137
+
8. Commit your changes (replace the message with a description of your changes):
126
138
127
139
```shell
128
-
git commit -m 'Fixed typing error in <document name>'
140
+
git commit -m 'Fixed typo in install-audit-log-filter.md'
129
141
```
130
142
131
-
9. Open a pull request to Percona:
143
+
9. Push your branch to your fork:
132
144
133
145
```shell
134
-
git push <my repo><my_changes>
146
+
git push -u origin<my_changes>
135
147
```
136
148
149
+
10. On GitHub, navigate to your fork and click **Create pull request** to open a pull request to the Percona repository.
150
+
137
151
### Building the documentation
138
152
139
-
To verify your changes, you can use a MkDocs commandto build HTML.
153
+
To verify your changes, you can use MkDocs to build and preview the documentation locally.
140
154
141
-
Follow the [MkDocs Installation](https://www.mkdocs.org/user-guide/installation/) instructions.
155
+
1. Install the required dependencies:
142
156
143
-
After the installation, in the root directory, run the following command to build the documentation:
157
+
```shell
158
+
pip install -r requirements.txt
159
+
```
144
160
145
-
```shell
146
-
mkdocs serve
147
-
```
161
+
2. In the root directory, start the local development server:
3. Open your browser and navigate to `http://127.0.0.1:8000/` to view the documentation. The server automatically reloads when you make changes to the files.
152
168
153
-
Open a browser and navigate to `http://127.0.0.1:8000/percona-server/8.4/`, `http://127.0.0.1:8000/percona-server/8.0/` or `http://127.0.0.1:8000/percona-server/5.7/`to see the HTML files. You may need to navigate to the document that you have changed.
169
+
4. Navigate to the document you changed to verify your edits.
154
170
155
171
### Building the PDF documentation
156
172
157
-
To build the PDF documentation, open the `site/print_page.html`in your browser, for example, https://docs.percona.com/percona-server/8.4/print_page.html. Save it as PDF. Depending on the browser, you may need to selectthe**Export to PDF**, **Print - Save as PDF** or just **Save** and selectPDF as the output format.
158
-
159
-
## Repository structure
160
-
161
-
The repository includes the following directories and files:
162
-
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
-
- `_static` - images, logos and favicons
168
-
- `_templates` - the template for the PDF cover page
169
-
- `css` - styles
170
-
- `js` - Javascript files
171
-
- `_resource`:
172
-
- `templates`:
173
-
- ``styles.scss`` - styling for PDF documents
174
-
- `theme`:
175
-
- `main.html` - the layout template for hosting the documentation on Percona website
176
-
- `overrides` - the folder with the customized templates
177
-
- `_resourcepdf` - the folder with customized templates for PDF output
178
-
- `.github`:
179
-
- `workflows`:
180
-
- `main.yml` - the workflow configuration for building documentation with a GitHub action. (The documentation is built with `mike` tool to a dedicated `publish` branch)
181
-
- `site` - this is where the output HTML files are put after the build
173
+
!!! tip "Browser recommendation"
174
+
175
+
This procedure works best in Google Chrome. Other browsers may not render the PDF correctly.
176
+
177
+
To build the PDF documentation:
178
+
179
+
1. Build the documentation site:
180
+
181
+
```shell
182
+
mkdocs build
183
+
```
184
+
185
+
2. Open the `site/print_page.html` file in Chrome. You can do this by:
186
+
187
+
* Navigating to the file in your file manager and double-clicking it, or
188
+
189
+
* Opening Chrome and using **File > Open File** to navigate to `site/print_page.html`
190
+
191
+
3. In Chrome, press `Ctrl+P` (or `Cmd+P` on Mac) to open the Print dialog, or select**Print** from the menu.
192
+
193
+
4. In the Print dialog:
194
+
195
+
* Set the **Destination** to **Save as PDF**
196
+
197
+
* Adjust any print settings as needed (margins, paper size, etc.)
198
+
199
+
* Click **Save** and choose where to save the PDF file
0 commit comments