DevDocs Contributions

Share your knowledge with the community by contributing to Magento DevDocs! You can contribute by creating an issue or pull request (PR) on our devdocs GitHub repository. We welcome all types of contributions; from minor typo fixes to new topics. As you contribute PRs, you can also gain Contribution Points with Community Engineering.

Magento’s team of technical writers reviews all issues and pull requests on a regular basis, and we do our best to address all issues as soon as possible. Working through the backlog takes time, though, so we appreciate your patience.

If you are not sure where to start contributing, you can review our list of suggested topics.

If you write and contribute a full topic, we will put your name (or your company’s name) at the top of the page right under the title, and link it to your blog or website! We will also add your picture and a link to your GitHub account on the Top recent contributors page.

Contribution guidelines

We use Markdown to write our documentation, which is a simple markup language that we convert to HTML using Kramdown.

You can update, or add content to, existing topics in their respective versioned directories (for 2.0, 2.1, 2.2, and onward).

We provide templates to help get you started writing a new topic:

Refer to the Magento Contributor Agreement for detailed information about licensing. All contributors are required to submit the form and agree to the terms.

The following guidelines may answer most of your questions and help you get started:

  1. Check existing pull requests and make sure you are not duplicating work!

  2. For large contributions or changes that include multiple files, open an issue and discuss it with us first. This may further prevent duplicate or unnecessary effort.

  3. Familiarize yourself with the existing documentation. Look through the guides to decide where to add your topics.

    • The DevDocs team can find the best home for your new topics and add it to the navigation.
    • If a topic has a symlink, you can remove it with git commands and add a new file. Copy and paste a previous version of the topic to get started.
  4. Focus on the content and on creating useful information for your fellow Magento developers and community members. Don’t forget to review your work for typos, formatting errors, or sentences that need clarifying before opening a pull request.

  5. Use the following guidelines to help you with the writing process:

    • Define the goal of your topic. What exactly do you want to teach the reader?
    • Make the title of your topic reflect the content.
    • Keep your sentences concise and try to separate conceptual information from procedural steps.
    • Remember to use active voice (not passive), write in the present tense, and use a friendly tone in second person. For example, “You can now view the output…“.
    • Use notes to alert readers about important details.
    • Use cross-references to other topics if appropriate. We can help you with the syntax if it is not clear. The template provides an example you can use.

Fork and clone a repository

Use the fork and pull model to contribute to Magento DevDocs. This model requires you to keep your forked repository in sync with the upstream repository. You submit pull requests to pull a set of changes from your forked repository to the upstream repository.

To fork the devdocs repository on GitHub, do the following:

  1. Create or log into your development environment account on GitHub.

  2. Navigate to the DevDocs repository.

  3. Click Fork at the top right.

  4. Clone the repository into your development environment and start writing and committing your changes. Optionally, create a branch first if you plan to work on multiple changes.

  5. To preview your changes in HTML output, follow the instructions in the README to build the devdocs site locally using Jekyll.

  6. Before opening a pull request, don’t forget to review your work for typos, formatting errors, code sample formatting, or sentences that need clarifying.

Update your fork

As we merge changes with the upstream repository, your fork becomes outdated and pull requests might result in merge conflicts.

To see if your fork is outdated, open the fork page in GitHub. If you see the following message at the top of the page, update your fork: This branch is <number> commits behind develop.

There are two ways to update your fork. The typical way is discussed in GitHub documentation. Ensure you are updating your fork from the correct branch.

It is also possible to use the GitHub interface to update your fork. This is referred to as a reverse pull request. This method has the downside of inserting unnecessary information into fork commit history.

  1. Navigate to the GitHub page for your forked repository and click New pull request. You should see the following message:

    There isn’t anything to compare.
    magento:2.1 is up to date with all commits from <your fork>:2.1. Try switching the base for your comparison.
  2. Click the base link and then click Create pull request.

  3. Enter a name for your pull request.

  4. Scroll to the bottom of the page and click Merge pull request.

  5. Click Confirm Merge.

Create a pull request

To create a pull request do the following:

  1. Push your changes to your forked repository on GitHub.

  2. In your forked repository, click New pull request.

  3. Be sure to create the pull request on the develop branch. We do not accept pull requests on other branches, like gh-pages.

  4. Review the changes, then click Create pull request.

  5. Fill out the form and click Create pull request again to submit the pull request—that’s it!

Report an issue

If you find a typo or erroneous information in Magento DevDocs, you can either fix it with a pull request (as described above) or you can report it by creating an issue in the DevDocs GitHub repository.

GitHub issues use templates for requested information. Enter as much information as you can including content corrections, steps to reproduce, command or code updates, or questions for clarifications.

Check the existing issues on GitHub to see if someone has already reported the issue.

You have a couple of options to enter an issue:

  • Have general feedback? Create an issue on GitHub DevDocs.
  • Have feedback on a specific DevDocs page? Click the Report an Issue link at the top right of the page to report on the currently open topic.
  • Have a Community code contribution? Create an issue to request DevDocs content.

Edit metadata

The Markdown (.md) file’s metadata is a set of YAML key-value pairs. The metadata section is located at the top of each file.

group: install2
title: Continue with your installation
version: 2.1
GitHub_link: install-gde/

Refer to the following table for a description of each key-value pair.

Key-value pair Description
layout: default Selects the template Jekyll will use to render the .md file into HTML and CSS.
group: install Defines which guide the file belongs to and which left-hand menu collection the file will show up in. What you put here does not affect the top navigation menu, which is controlled by the `_/includes/navigation.html` file.
title: Install Magento Sets the title of the page in the HTML meta and the main title on the page.
version: 2.1 Specifies which version(s) of Magento the topic affects. We also use this data to build links to the file on GitHub.
GitHub_link: install-gde/ Specifies the name and location of the source file in the GitHub repository.

Add a Contributor’s name to a topic

When a community member contributes an entire topic—or makes substantial improvements to an existing topic—we like to thank them by adding their name (or company name) beneath the topic title and a link to their blog or website.

Thank you for contributing your brilliance to Magento DevDocs!!