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.

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 write and contribute a full topic, we will put your name (or 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. We have a template to make getting started easy.

1. First, 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 prevent duplicate or unnecessary effort.

3. Familiarize yourself with the existing documentation; taking a look at what is already there will help you decide where your topic best fits. The DevDocs team can also help find the best home for your new topics.

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 in to 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 then start writing and committing your changes. Optionally, create a branch first if you plan to work on multiple changes.

5. Build the devdocs site locally using Jekyll by following the instructions in our README.

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, you must 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. Make sure to update 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. Go to your forked repository GitHub page, click New pull request. You should see the following message:

   There isn’t anything to compare.
   magento:2.0 is up to date with all commits from <your fork>:2.0. 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.

All topics on this site contain a link to the Issues panel on Github, which makes it easy to report issues on specific topics. Click the Give us feedback link at the top left of the page to open an issue for that page.

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.

---
layout: default
group: install2
title: Continue with your installation
version: 2.1
github_link: install-gde/continue.md
---

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

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

In the metadata section at the top of the file, add these two entries:

contributor_name: <name_of_contributor>
contributor_link: <link_to_contributors_site_or_blog>

Thank you for contributing your brilliance to Magento DevDocs!!