Skip to content

Latest commit

 

History

History
565 lines (410 loc) · 18.2 KB

CONTRIBUTING.md

File metadata and controls

565 lines (410 loc) · 18.2 KB
Raw

Contributing to the Mautic documentation

This repository serves as the documentation for Mautic, the open source marketing automation system.

Everyone is welcome to contribute to improve this information as needed.

Why git

Why is git used for the documentation

  • versions - anyone can go back and look at what the text looked like.
  • authorship - not only every file, but every line has its author.
  • community contributions - no need to worry about deleting someone else's work while working on the same document.

Although some git knowledge is required to clone, modify, commit and push changes, there is a way to avoid that and edit the files directly in the GitHub web interface or via our web-based interface using the Grav CMS. If you know git, use the workflow you like. If not, the following guide will show you how to contribute easily.

Why Grav

Previously Gitbook was used to manage the Mautic documentation, however this became cumbersome to maintain, and difficult for those who were not familiar with Git. The Education Team looked into various solutions and decided that Grav would best meet the needs of the Community.

How to contribute

Using Grav

  1. Create a Mautic Community login, or log in with your existing forum/website account at the login page
  2. Send a message in the Documentation slack channel to have your account raised to 'editor' - get a Slack invite here
  3. When logged in, click on the 'Edit page in Grav' link on the relevant page and make your changes

Using Github

  1. Fork this repository at GitHub
  2. Select a file to edit on your fork
  3. Make your commits
  4. Open a pull request to base fork: mautic/documentation with base: master
  5. Include and reference any Issues your Pull Request addresses

Editing documentation using the command line

  1. In the command line cd to where you want the documentation repository located

  2. Clone this repository

    git clone https://github.com/mautic/documentation.git --origin upstream

  3. Fork this repository at GitHub or use the hub utility

    hub fork --remote-name origin

  4. Once cloning has completed, open the project in your editor of choice

  5. Create a new branch for your edits. Please name your branch something descriptive like {yourusername}-revision-readme-file

    git checkout -b {yourusername}-revision-readme-file upstream/master

  6. Make your changes

  7. Stage and commit your changes to your local repository

    git status --short
git add <new and modified files>
git commit --message 'move contributing to new file'

  8. Push to origin

    git push origin

  9. Review the changes at your fork https://github.com/{yourusername}/mautic-documentation

  10. Submit your pull request using one of these methods

    • Direct link: https://github.com/{yourusername}/mautic-documentation/pull/new/{yourusername}-revision-readme-file
    • GitHub web interface - base fork: mautic/documentation and base: master at GitHub
    • use the hub utility
    hub pull-request

Editing documents in the GitHub browser interface

Note
If you're unfamiliar with the command line but still want to contribute to the Mautic documentation

Using README.md as an example:

  1. Fork this repository under your account so you'll have permission to edit.
  2. Select the README.md file (refer to the file structure section below if needed)
  3. With the content of README.md visible, click on the pencil icon to begin editing the file
  4. The .md extension means this file was written in Markdown, a simple but flexible text formatting language. Mautic documentation is written with Markdown markup specifically.
  5. After you've made a change, scroll down to the Commit changes form. Saving your change requires describing what was changed and why.
  6. Before submitting your commit, select the box for Creates a new branch to start a new branch for your change. Name your branch something like {yourusername}-revision-readme-file
  7. Select Propose file change
  8. In the next dialogue box, describe what you've changed and why then select Create pull request to open a pull request proposing we add your changes to our official repository.

File Structure

The README.md file serves as the introduction and description of this repository. This file does not contain any product documentation.

The SUMMARY.md file defines the menu of the documentation. If you add a new page to the documentation, you'll have to also add a new line there defining the title and the link to the file (formatted like the existing menu items).

The folders in this repository are grouped together by topic. For example, within the asset folder, you'll see it has its own README.md file (becomes ./index.html) which contains the primary description of the Asset menu; the manage_assets.md file is a subitem; the media subfolder contains all the images used in the .md files.

Style Guide

The style guide section is very much a 🚧 Work in Progress.

Please contribute :)

Whitespace and spaces

  • One blank line around headings

  • One blank line around list items

  • One blank line around code blocks

  • One final blank line

  • Two spaces after a full stop. Next sentence.

Lists

  • Use 1. for numbered lists.
  • Use 1. only for numbered lists.
  • Use - for unnumbered lists
    • Indent spaces until first character of content in line above
    • which is effectively 2 spaces for nested unnumbered lists
example list
Example nested list
  1. Item the first
  2. Something else
    1. indent spaces until first character of content in line above
    2. that means line up on the S in Something
      1. and the first t in that
  3. And finally
    • minor point from the A
  • not part of the numbered list
markdown syntax
Nested list markdown syntax
1. Item the first
1. Something else
   1. indent spaces until first character of content in line above
   1. that means line up on the `S` in `Something`
      1. and the first `t` in `that`
1. And finally
   - minor point from the `A`

- not part of the numbered list

Code blocks

  1. Prefer fenced <codeblock>s with three backticks
  2. Must have language identifier
    • Use text if no highlighting required
  3. Fenced code blocks within lists need to be indented for numbered lists to continue
example codeblock
Example <codeblock>
/**
 * Constructor.
 *
 * @param string $environment The environment
 * @param bool   $debug       Whether to enable debugging or not
 *
 * @api
 */
public function __construct($environment, $debug)
{
    defined('MAUTIC_ENV') or define('MAUTIC_ENV', $environment);
    defined('MAUTIC_VERSION') or define(
        'MAUTIC_VERSION',
        self::MAJOR_VERSION.'.'.self::MINOR_VERSION.'.'.self::PATCH_VERSION.self::EXTRA_VERSION
    );

    parent::__construct($environment, $debug);
}
A markdown syntax
<codeblock> markdown syntax
/**
 * Constructor.
 *
 * @param string $environment The environment
 * @param bool   $debug       Whether to enable debugging or not
 *
 * @api
 */
public function __construct($environment, $debug)
{
    defined('MAUTIC_ENV') or define('MAUTIC_ENV', $environment);
    defined('MAUTIC_VERSION') or define(
        'MAUTIC_VERSION',
        self::MAJOR_VERSION.'.'.self::MINOR_VERSION.'.'.self::PATCH_VERSION.self::EXTRA_VERSION
    );

    parent::__construct($environment, $debug);
}
example nested codeblock
Example nested <codeblock>

  1. START list item

    Example nested <codeblock>

    /**
 * Constructor.
 *
 * @param string $environment The environment
 * @param bool   $debug       Whether to enable debugging or not
 *
 * @api
 */
public function __construct($environment, $debug)
{
    defined('MAUTIC_ENV') or define('MAUTIC_ENV', $environment);
    defined('MAUTIC_VERSION') or define(
        'MAUTIC_VERSION',
        self::MAJOR_VERSION.'.'.self::MINOR_VERSION.'.'.self::PATCH_VERSION.self::EXTRA_VERSION
    );

    parent::__construct($environment, $debug);
}

  2. END list item

markdown syntax
Nested <codeblock> markdown syntax
    ```php
    /**
     * Constructor.
     *
     * @param string $environment The environment
     * @param bool   $debug       Whether to enable debugging or not
     *
     * @api
     */
    public function __construct($environment, $debug)
    {
        defined('MAUTIC_ENV') or define('MAUTIC_ENV', $environment);
        defined('MAUTIC_VERSION') or define(
            'MAUTIC_VERSION',
            self::MAJOR_VERSION.'.'.self::MINOR_VERSION.'.'.self::PATCH_VERSION.self::EXTRA_VERSION
        );

        parent::__construct($environment, $debug);
    }
    ```

Links

Often you'll want to make a link to another place in the documentation. We prefer to group links at the bottom of a page, and provide a reference macro in the text. This make linking to the same place much easier. In Markdown, it looks like this:

Absolute links

Aut et laudantium ad ratione id. Ut similique quis et ut. Consectetur eum quia totam recusandae necessitatibus dolorem debitis.

Aut et laudantium ad [ratione id][link macro]. Ut similique quis et ut.
Consectetur eum quia totam [recusandae][link macro] necessitatibus dolorem debitis.

[link macro]: <http://example.com>

Relative links

These will link to plugins/integration_test.html on the documentation website created from the plugins/integration_test.md source file.

The first line is an example from within the same section. The second for anywhere else in the directory structure.

[testing]: <integration_test.html>

[testing]: <./../plugins/integration_test.html>

Heading anchors

Heading anchors enable linking directly to a Markdown heading from within the same document very easily. The anchors are auto-generated for all headings. The link target is specified inline.

Aut et laudantium ad [ratione id](#heading-anchors). Ut similique quis et ut.
Consectetur eum quia totam [recusandae](#style-guide) necessitatibus dolorem debitis.

Images

Images should be placed in the media subfolders in the different sections of this repository.

Link format:

![alternative text here](image-reference.png "Tooltip text here")

relative image links

To display an image already in the documentation repository, use a relative path.

The first line is an example of using images in the same section. The second for anywhere else in the directory structure.

![form rebuild cache](media/rebuild.png "Rebuild form cache"")

![form rebuild cache](./../forms/media/rebuild.png "Rebuild form cache")

absolute image links

For images that cannot be uploaded via the GitHub web interface, upload them to a public URL service and use the generated link.

![apple](http://example.com/images/apple.png "Like this delicious apple")

Warning

internal absolute image link

This link format should NOT be used.

![form rebuild cache](/forms/media/rebuild.png "Rebuild form cache")

Mautic specific information

Example domain references

Use example.com as the reference domain for documentation.

For the various installation types, use

  • standard Mautic URL example

    https://example.com

    • include www if relevant

      https://www.example.com

  • Mautic installed as subdomain URL

    https://mautic.example.com

  • Mautic installed as subdirectory URL

    https://example.com/mautic

Protocol scheme: http vs https

  • Prefer the https:// protocol in documentation.

    https://example.com

  • If you need to show both protocols, add brackets around the (s)

    http(s)://example.com

Linking to Release versions

  • Use an absolute external link to reference the official released versions of Mautic. The project adheres to Semantic Versioning, so all version numbers have three components: <MAJOR>.<MINOR>.<PATCH>

  • Prefix the version with the word Mautic in the text, and the full three-part version number in the link macro.

    • A <MAJOR>.<MINOR> release version without <PATCHES> may be used in the text, but still use the full three-part version number in the link.

  • Wrapping the version number in <code> backticks "`" is optional.

Since Mautic 2.9, when...

Since [Mautic `2.9`][release-2.9.0], when...

[release-2.9.0]: <https://github.com/mautic/mautic/releases/tag/2.9.0>

latest version

Avoid using the term current or latest if you actually mean "the currently released version of Mautic that I installed".

In most cases, it has no meaning when a new version is released. Instead, check the latest release and explicitly use that version number.

Do NOT do this:

In the latest version of Mautic...

DO this instead:

In Mautic 2.15.3 ...

> In [Mautic `2.15.3`][release-2.15.3] ...

[release-2.15.3]: <https://github.com/mautic/mautic/releases/tag/2.15.3>

References to leads and lead lists

Include this Note if there are references to outdated terminology that cannot be updated.

Note

In this document, there may be references to outdated terminology such as

  • leads,
  • lists or lead lists, and
  • anonymous leads

In Mautic version 1.4,

  • leads were renamed to contacts
  • lead lists were renamed to segments
  • anonymous leads were renamed to visitors
markdown syntax
reference note
> **Note**
>
> In this document, there may be references to outdated terminology such as
>
> - _leads_,
> - _lists_ or _lead lists_, and
> - _anonymous leads_
>
> In [Mautic version `1.4`][release-1.4.0],
>
> - _leads_ were renamed to _**contacts**_
> - _lead lists_ were renamed to _**segments**_
> - _anonymous leads_ were renamed to _**visitors**_

[release-1.4.0]: <https://github.com/mautic/mautic/releases/tag/1.4.0>