/docs

Mattermost documentation

Primary LanguageHTML

Mattermost Documentation

This repository generates the documentation available at https://docs.mattermost.com/. All documentation is available under the terms of a Creative Commons License.

If you have any questions, sign up to community.mattermost.com and join the Documentation channel.

Table of Contents

Contributing

Getting Started

You can edit or create Mattermost documentation directly in GitHub or by downloading the repo onto your machine and using an editor such as Atom. Consult the Mattermost Documentation Style Guide and reStructuredText Markup section for stylistic and technical guidance.

If this is your first time contributing to Mattermost, first read the Mattermost Contributor Agreement and sign it (at the bottom of the page), so you can be added to the Mattermost Approved Contributor List.

Editing

The quickest way to begin is editing directly on GitHub on your fork of the Mattermost docs repo. Click the Edit icon on the top right corner of the page you want to edit in the Mattermost documentation.

If this is the first time you're contributing, follow these steps:

  1. Select Fork in the top-right corner of the GitHub page to fork the repository.
  2. Navigate to file you want to edit and select the Pencil icon (Edit the file) to open the editing interface.

Creating Pull Requests

  1. When you're ready to submit your changes, add a descriptive title and comments to summarize the changes made.
  2. Select Create a new branch for this commit and start a pull request.
  3. Check the Propose file change button.
  4. Scroll down to compare changes with the original document.
  5. Select Create pull request.

Using Labels

Labels are used to track the lifecycle and status of a pull request. Using the correct labels helps with managing workflows and ensuring that content is edited, merged and released at the correct time. Take a look at the Labels page for information about how and when to use which labels.

Commenting on Pull Requests

Once a pull request is submitted, multiple committers may comment on it and provide edits or suggestions which you can commit directly. You can also add line comments. Take a look at Commenting on pull requests for more details.

Reviewing Pull Requests

Once a pull request has been submitted and the correct label assigned, the review process begins. This includes aligning the content with the Style Guide, validating processes, and tagging any other relevant committers. You can read more about the review process and expectations here.

Once the review process is complete and depending on the type of issue it is (e.g., a typo fix vs. a new feature), the change is either merged into master and pushed immediately or merged into the release branch and pushed in alignment with the release. The branch is then deleted.

Any merged PRs with an Editor Review or Reviews Complete label will be processed by the editor reviewer to ensure the documentation is correctly formatted at https://docs.mattermost.com/.

Building and Validating

If you've downloaded the repository and are editing Mattermost documentation on your local machine, you can generate the HTML files from markdown in the /source directory. You can review your changes before you commit them or create pull requests.

Note: Commands can be executed on Linux, Mac, and Windows (using Powershell).

  1. Open a terminal window, then clone a forked copy of the documentation repository by running the following command::
git clone https://github.com/mattermost/docs.git
  1. Install pipenv by using one of the following commands based on your operating system:

For Mac users where Homebrew is installed:

brew install pipenv

For other operating systems

pip install pipenv
  1. In the terminal window, navigate into the cloned repository:
cd docs
  1. Install the required packages by running the following command:
pipenv install
  1. Build the documentation set using make html. This generates files in /build directory.
  2. Navigate to the /build directory to preview your changes by running the following command:
cd /build

The build process may generate this error: WARNING: toctree contains reference to document u'foo' that doesn't have a title: no link will be generated. It can be ignored as it does not negatively impact the documentation.