Doc contributions

Share your knowledge with the community by contributing to Commerce technical documentation! We welcome all types of contributions; from minor typo fixes to new topics.

You can contribute by creating an issue or pull request (PR) in one of our GitHub repositories. Click one of the following buttons at the top of any documentation page:

Adobe staff members and community maintainers review issues and pull requests on a regular basis. We do our best to address all issues as soon as possible, but working through the backlog takes time. We appreciate your patience.

Contributor attribution

If you write and contribute a new topic, we add your name (or your company's name) at the top of the page and link it to your GitHub profile (or company website)! For example:

Get started

1. Make sure you have a GitHub account.
2. Fork the AdobeDocs repository that you want to contribute to. Remember to sync your fork and update branches as needed.
3. Review the contribution guidelines.

Contribute documentation

The following diagram shows the contribution workflow:

Project boards

New issues and PRs automatically appear in the following GitHub project boards:

• Commerce - Issues—If you are not sure where to start contributing, search for issues with the help wanted and good first issue labels. These issues receive higher priority for processing.
• Commerce - Pull Requests—Track the progress of all PRs.

Create a branch

1. Create a branch from your fork using a name that best describes the work or references a GitHub issue number.
2. Edit or create markdown (.md) files in your branch.
3. Push your branch to your fork.

Create a pull request

1. Create a pull request to the target AdobeDocs repository.

   In general, you should use main as the base branch when creating a PR. If your contribution is related to a release that is in progress, use a version-specific integration branch, such as develop.

2. Complete the pull request template.

   We will close your pull request if you do not complete the template.

3. After creating a pull request, an Adobe staff member or maintainer will review it and may ask you to make revisions.

   We will close your pull request if you do not respond to feedback in two weeks.

Contribution guidelines

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

• Write content using Markdown.

• Review existing pull requests and issues to avoid duplicating work.

• For large contributions, or changes that include multiple files, open an issue and discuss it with us first. This helps prevent duplicate or unnecessary work.

• Do not make global find-and-replace changes without first creating an issue and discussing it with us. Global changes can have unintended consequences.

• Combine multiple small changes (such as minor editorial and technical changes) into a single pull request. This helps us efficiently and effectively facilitate your contribution.

• Familiarize yourself with the organization and conventions of our existing documentation before creating a pull request. Changes that are consistent with our style and conventions have a higher acceptance rate.

  • If you need to update the site navigation, ask for help in Slack (#devdocs).

• Review your work for basic typos, formatting errors, or ambiguous sentences before opening a pull request.

• Revise pull requests according to review feedback. We will close pull requests that require an inordinate amount of time to review and process (especially for minor changes) if you fail to make revisions according to review feedback.

• Do not directly contact Adobe team members or maintainers on Slack to review your pull request unless it has been open for more than five days. We have a process and queue for pull requests that everyone must follow.

• Get recognized on the Adobe web site for writing new topics! Add your name and a link to your company website or GitHub profile to the file metadata so that we can display it on the page. See Edit metadata.

• We no longer recognize individual community members who contribute features to the Magento 2 codebase in the corresponding feature topic(s) in the documentation. Adobe recognizes these contributions in more appropriate channels (for example, the Magento DevBlog).

Tips for writing content

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

• Focus your efforts on providing useful information for your fellow Adobe Commerce and Magento Open Source developers and community members. For example, consider providing or revising code samples, important notes, and clarifying vague or ambiguous content.
• 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. Separate conceptual information from procedural steps.
• Batch several small changes into a single pull request (instead of separate ones) to ensure that your contributions are approved and merged quickly. Have several typo fixes across several areas of documentation? Combine them into a single PR.
• Remember to write in present tense, use the second person, and use active voice (not passive). For example, "The log captures commands, output...".
• Use notes to alert readers about important details.
• Use cross-references to other topics sparingly. We can help you with the syntax if it is not clear. The template provides an example that you can use.

Review changes locally

(Optional) To review your changes in HTML output, follow the instructions in the repo's README to build the site locally using Gatsby.

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.

Copy
---
title:
description:
contributor_name:
contributor_link:
---
Copied to your clipboard
---
title:
description:
contributor_name:
contributor_link:
---

Key-value pair reference:

Report an issue

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

You must complete the issue template. We will close your issue if you fail to complete the template. Enter as much information as you can, including content corrections, steps to reproduce, command or code updates, or questions for clarifications.

You can provide feedback using the following options:

• Have general feedback? Create an issue in the corresponding AdobeDocs GitHub repo.
• Have feedback on a specific page? Click the Edit in GitHub link at the top right of the page to report on the currently open topic.
• Have a Community code contribution that needs documentation? Create an issue in the corresponding AdobeDocs GitHub repo.

Thank you for contributing to the documentation!

Last updated 1/10/2024

Was this helpful?

Yes

No