Skip to content

Latest commit

 

History

History
142 lines (93 loc) · 5.44 KB

CONTRIBUTING.md

File metadata and controls

142 lines (93 loc) · 5.44 KB

Contributing guide

Welcome to Percona Software Release documentation! This documentation describes percona-release - the repositories management tool. percona-release simplifies the process of subscribing to Percona repositories which enables you to install/update Percona software and all required dependencies using the package manager of your operating system.

We're glad that you would like to become a Percona community member and participate in keeping open source open.

This repository contains the source file for percona-release documentation and this document explains how you can contribute to it.

Contribute to documentation

percona-release 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.

Before you start, learn what git, MkDocs and Docker are and what Markdown is and how to write it. For your convenience, there's also a cheat sheet to help you with the syntax.

The doc files are in the docs directory.

Edit documentation online via GitHub

  1. Click the Edit this page icon next to the page title. 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 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 git@github.com:<your_name>/repo-config-docs.git
  1. Change the directory to repo-config-docs and add the remote upstream repository:
git remote add upstream git@github.com:percona/repo-config-docs.git
  1. Pull the latest changes from upstream
git fetch upstream
git merge upstream/master
  1. Create a separate branch for your changes
git checkout -b <my_branch>

  1. Make changes

  2. Commit your changes. The commit message guidelines will help you with writing great commit messages

  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 our 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.

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 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.

Install MkDocs and build locally

  1. Install Python.

  2. Install MkDocs and required extensions:

    pip install -r requirements.txt

  3. Build the site:

    mkdocs build

  4. Open site/index.html

Or, to run the built-in web server:

mkdocs serve

View the site at http://0.0.0.0:8000

Repository structure

The repository includes the following directories and files:

  • mkdocs.yml - the configuration file. It includes general settings and documentation structure.
  • docs:
    • *.md - Source markdown files.
    • _images - Images, logos and favicons
    • css - Styles
    • js - Javascript files
  • _resource:
    • theme:
      • main.html - The layout template for hosting the documentation on Percona website
    • overrides - The folder with the Material theme template customization for builds
  • site - This is where the output HTML files are put after the build