Skip to content

Branches to PRs

Jump to bottom
Shrie Spangler edited this page Oct 22, 2020 · 11 revisions

Learn more about committing updates to branches and submitting pull requests. If you write documentation on your local computer, clone the repository to branch, write, commit, etc.

Working with Git and GitHub

Before you begin, consider how you want to work with Git. All instructions include Git commands and GitHub Desktop options.

If you have developer experience, you can use Git commands using a terminal.

For ease of committing and pushing content, GitHub provides GitHub Desktop. Clone your fork, create branches, commit documentation updates, and push branches to GitHub all through one simple interface! For help, see their documentation.

Clone the fork

To work on your local computer, you need to clone the fork locally. You need the repository link from your fork.

To clone using Git, create or change directories in a terminal and enter the following command. Use the HTTPS or SSH link. With SSH, you may need a token or SSH key added.

git clone <link to git repository>

In GitHub Desktop, click Open in Desktop. The clone options open in the application. Select a location and clone.

Create branch

2.4 updates - start from master

To create a branch in Git from master, in a terminal enter the following command:

git checkout -b <branchname>

In GitHub Desktop, click Current Branch then New Branch. Enter a name. You are automatically on that branch to start working.

2.3 updates - start from 2.3-production

First, you must checkout the 2.3-production branch. In a terminal, enter the following command:

git checkout 2.3-production

To create a branch in Git from the production branch, enter the following command:

git checkout -b <your-branchname>

In GitHub Desktop, use the branch switcher to checkout the 2.3-production branch, click Current Branch, and then click New Branch.

Enter a name. You are automatically on that branch to start working.

Commit changes

As you edit and saved documentation, you "commit" the changes to your branch. Each commit can be one or more files. Enter a commit message to collect changes for pushing to your branch on GitHub.

To commit using Git, in a terminal enter the following command:

git commit -m "<commit message title>"

In GitHub Desktop, enter a summary and details then click Commit.

Commit messages

When providing your contribution to Magento Documentation, it is important to accompany it with a meaningful commit message.

A meaningful commit message is important to:

  • Help speed up the reviewing process
  • Help us write a good release note
  • Help future writers and developers understand why a particular change was made

Provide a summary commit message followed by details, as needed to best describe your work.

For example:

Updated Inventory docs with InStore Pickup
- Added new terms for InStore Pickup
- Added InStore Pickup to diagrams

Issue numbers

If writing content for a GitHub issue, we recommend including the GitHub issue number and title with your comments that you feel are relevant. Adding the GitHub issue, your commit is automatically linked to this issue. Everyone can quickly see your committed work and the issue associated to it in GitHub.

magento/merchdocs#<issue-number>: <issue-title>
- <additional comment>

For example:

magento/merchdocs#123: Add InStore Pickup to Inventory docs
- Added new terms for InStore Pickup
- Added InStore Pickup to diagrams

Push your branch

After committing your changes, push your branch to GitHub to generate a Pull Request.

To push using Git, in a terminal enter the following command:

git push -u origin <branch name>

In GitHub Desktop, select the option to push.

Submit a pull request

A pull request (PR) creates a manifest list of files you added or edited. We review this collection of files and merge it to update documentation.

  1. Open your forked repository in GitHub.

  2. Click Pull requests and then click New pull request.

  3. Select the master (2.4) or 2.3-production (2.3) branch for the base.

    The branch you select as your base should be the same one from which you created the branch that contains your work.

  4. Click Create pull request.

  5. Enter a PR name and fill out the PR form. Here are some tips!

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

    • If your PR is a solution to an existing issue include any related GitHub Issue(s) links.

    • Describe the content you added or changed.

    • Include URLs to existing Magento Admin User Guide pages you are updating.

    • If your PR is considered a new topic, a major update, or technical revisions/addition, add a whatsnew to your PR. At the bottom of the PR, add the text whatsnew immediately followed by a sentence explaining your change and a link to the affected topic.

      Often, the information you add to the whatsnew is the same description you add in the PR, with the addition of a docs topic link--You can simply copy your PR description and add a link and more context to complete your whatsnew addition!

      Example:

      whatsnew
Updates across Page Builder topics to reflect [workspace](https://docs.magento.com/user-guide/cms/page-builder-workspace.html) changes for editing in full-screen mode only.

      This is added to our What's New page to keep everyone up-to-date about documentation changes.

  6. Click Create pull request again to submit the PR. That’s it!

For first-time contributors only: After the PR is created, you should see two comments requesting you take actions:

  • Fill out and digitally sign the Adobe Contributor Agreement. This is required for merging PRs to Magento open source repositories.
  • Accept the invite to the Magento organization. After accepting the invitation, you can assign/claim issues (including the one associated to your PR)!

After submitting your PR, you can find it in the MerchDocs Pull requests section or the PRs for your special project.

PR process

Your PR undergoes reviews and testing by the Magento Documentation team before merging.

Watch your email or the PR in GitHub for feedback on your PR! Reviewers may respond asking for changes.

What happens to your PR:

  1. Magento Documentation team members review PR content including edits and additions, grammar, formats, images, etc.
  2. Reviewers either request additional changes or approve the PR. If additional changes are needed, finish those for an additional review.
  3. After the PR is approved it is tested (verifying links, images, etc). When complete, we merge the PR.

The Magento Admin User Guide updates with your merged changes on an automated schedule. Any issue(s) linked to the PR also close as complete.

Tips for PRs

  • 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 (#merchdocs).
  • 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 Magento Documentation team members 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.

Contribution Guide

Projects

Documentation

Clone this wiki locally