Skip to content

Latest commit

 

History

History
137 lines (90 loc) · 5.41 KB

CONTRIBUTING.md

File metadata and controls

137 lines (90 loc) · 5.41 KB
Raw

Contributing Guide

Thank you for deciding to contribute and help us improve Percona Distribution for MongoDB documentation!

We welcome contributors from all users and community. By contributing, you agree to the Percona Community code of conduct.

Contribute to documentation

Percona Distribution for MongoDB documentation is written in Markdown language, so you can edit it online via GitHub. If you wish to have more control over the doc process, jump to how to edit documentation locally.

To contribute to the documentation, you should be familiar with the following technologies:

  • MkDocs documentation generator. We use it to convert source .md files to .html and PDF documents.
  • 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 derives from the major version of PostgreSQL, included in the distribution.

Each version has a branch in the repository named accordingly:

  • 4.2
  • 4.4
  • 5.0
  • 6.0

The source .md files are in the docs directory.

Edit documentation online via GitHub

  1. Click the Pencil 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 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 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.

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 repository on your machine:
git clone [email protected]:<your_name>/distmongo-docs.git
  1. Change the directory to distmongo-docs and add the remote upstream repository:
git remote add upstream [email protected]:percona/distmongo-docs.git
  1. Pull the latest changes from upstream
git fetch upstream
git merge upstream/<branch>

Make sure that your local branch and the branch you merge changes from are the same. So if you are on 4.2 branch, merge changes from upstream/4.2.

  1. Create a separate branch for your changes
git checkout -b <my_changes>
  1. Make changes
  2. Commit your changes
  3. 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

  1. Get Docker
  2. We use this Docker image to build documentation. Run the following command:
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.

  1. Go to the site directory and open the index.html file to see the documentation.
  2. To view your changes as you make them, run the following command:
docker run --rm -p 8000:8000 -v $(pwd):/docs perconalab/pmm-doc-md mkdocs serve -a 0.0.0.0:8000
  1. To create a PDF version of the documentation, run the following command:
docker run --rm -v $(pwd):/docs perconalab/pmm-doc-md mkdocs build -f mkdocs-pdf.yml

The PDF document is in the site/pdf folder.

Install MkDocs and 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
  1. Go to the site directory and open the index.html file in your web browser to see the documentation.
  2. To automatically rebuild the documentation and reload the browser as you make changes, run the following command:
mkdocs serve

  1. To build the PDF documentation, do the following:

    mkdocs build -f mkdocs-pdf.yml

The PDF document is in the site/pdf folder.