Documentation Contributing Guide

We welcome contributions from all users and the community. By contributing, you agree to the Percona Community code of conduct. Thank you for deciding to contribute and help us improve the Percona XtraBackup documentation.

You can contribute to the documentation in the following ways:

• Add a topic
• Request a doc change through a Jira issue
• Contribute to the documentation yourself

Add a topic

In the Percona Product Documentation category in the Percona Community Forum, select New Topic. Complete the form and select Create Topic to add the topic to the forum.

Request a doc change through a Jira issue

Request a doc change through a Jira issue. If you’ve found a doc issue (a typo, broken links, inaccurate instructions, etc.) create a Jira ticket to let us know about it if you would rather not contribute to the documentation yourself.

• Open the Jira issue tracker for the doc project.
• Sign in (create a Jira account if you don’t have one) and click Create to create an issue.
• In the following fields, describe the issue:
  • In the Summary, provide a brief description of the issue
  • In the Description, provide more information about the issue, along with a Steps To Reproduce section, if needed
  • In the Affects Version/s field, if you know this issue affects multiple versions, please enter the version numbers. It is OK to add the version number with an ".x" (such as 8.4.x) if you don't know the exact version that must be updated.

Contribute to documentation yourself

There is the pencil icon next to the page title 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.

To contribute to documentation, learn about the following:

• Markdown
• MkDocs
• git and GitHub
• 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 has a branch in the repository named accordingly:

• 8.0
• 8.4

The .md files are in the docs/ directory.

Edit documentation online using GitHub

1. Click the pencil icon next to the page title to edit the document. 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 of it for you.

2. Edit the page. You can check your changes on 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.

4. GitHub creates a branch and a commit for your changes. It loads a new page on which you can submit 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. At this time you can make a last-minute review. When you are ready, click the Create pull request button.

5. Someone from our team reviews the pull request. They may make a comment or they may approve it. We usually merge the approved pull request when Percona XtraDB Cluster is released.

Edit documentation locally

This option is for users who prefer to work from their computer and/or have the full control over the documentation process.

The steps are the following:

1. Fork this repository

2. Clone the forked repository to your machine:

   git clone git@github.com:<your_GitHub_account_name>
   

3. Change the directory to pxc-docs/docs and add the remote origin repository:

   git remote add origin git@github.com:percona/pxc-docs.git
   

4. To be sure that you have the latest changes, checkout the appropriate branch and pull the latest changes from origin

   git checkout 8.4 && git pull origin 8.4
   

   Make sure that your local branch and the branch you merge changes from are the same. So if you are on 8.4 branch, pull changes from origin 8.4.

5. Create a separate branch for your changes

   git checkout -b <my_changes>
   

6. Make changes in the documentation

7. Add the changed files

   git add <changed files>
   

8. Commit your changes

   git commit -m 'Fixed typing error in <document name>'
   

9. Open a pull request to Percona

   git push <my repo> <my_changes>
   

Building the documentation

To verify how your changes look, generate the static site with the documentation. This process is called building. You can use the following methods:

• use Docker
• build locally

Use Docker

1. Get Docker

2. We use our Docker image to build documentation. Run the following command in the docs directory:

   docker run --rm -v $(pwd):/docs perconalab/pmm-doc-md mkdocs build
   

   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.

   If you want to see the changes as you edit the docs, use this command instead:

   docker run --rm -v $(pwd):/docs -p 8000:8000 perconalab/pmm-doc-md mkdocs serve --dev-addr=0.0.0.0:8000
   

   Wait until you see the message INFO - Start detecting changes, then enter 0.0.0.0:8000 in the browser's address bar. The documentation automatically reloads after you save the changes in source files.

Build locally

1. Install pip

2. Install MkDocs.

3. While in the root directory of the doc project, run the following command to build the documentation:

   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:

   mkdocs serve
   

   Wait until you see the message INFO - Start detecting changes, then enter 0.0.0.0:8000 in the browser's address bar.

PDF

To build the PDF documentation, open the site/print_page.html in your browser, for example, https://docs.percona.com/percona-xtradb-cluster/8.4/print_page.html. 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.

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 with Material theme.
• docs:
  • *.md - source markdown files.
  • _static - images, logos and favicons
  • _templates - the template for the PDF cover page
  • css - styles
  • js - Javascript files
• _resource:
  • templates:
    • styles.scss - styling for PDF documents
  • theme:
    • main.html - the layout template for hosting the documentation on Percona website
  • overrides - the folder with the customized templates
• _resourcepdf - the folder with customized templates for PDF output
• .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