Quick Start: Update Existing Docs Through GitHub

Quick Start: Update Existing Docs Through GitHub#

Prerequisites

You need a GitHub account to create or edit documentation. You can create a Github account here.

To contribute to Open edX documentation, you must have a signed contributor agreement. For more information, see How to start contributing to the Open edX code base.

Edit a Topic#

Use the following instructions when you are viewing the published documentation on docs.openedx.org and you want to make changes to it.

  1. On the page you want to edit, under the GitHub icon in the header, GitHub Icon, select suggest edit.

  2. Make the necessary changes.

    Ensure you keep to RST standards in file. See the Quick Reference: Writing RST a quick reference to RST.

  3. In the Commit Changes section at the bottom of the edit window:

    1. Add a descriptive comment about the changes you made.

    2. Click Propose changes to save these changes to your branch.

      ../../_images/edit_in_github.png

GitHub then creates a fork of the repository that belongs to your account. A fork is a complete copy of the repository, plus your changes. For more information, see Github Forks.

GitHub then prompts you to create a pull request, which is a request for the Open edX team to integrate changes in your fork into the official repository.

Create a Pull Request for Your Change#

  1. In the Pull Request window, click Create pull request.

    ../../_images/create_pr_screen1.png
  2. You should not need to change the branches selected. By default, you are requesting to merge the branch in your fork of the repository into the official repository’s main branch.

  3. Add a unique, descriptive title for your pull request.

  4. Add a comment that explains your change to the Open edX team.

  5. Ensure the checkbox “Allow edits by maintainers” - this enables the Open edX team to rerun tests or make small changes, which will decrease the time for your changes to be accepted. Your screen should look like this:

    ../../_images/create_pr_screen2.png
  6. Click Create pull request.

The Open edX team will then review your changes. If they approve, they will merge the pull request, and you will see your changes in the latest documentation. The Open edX team may ask you to make further changes, to clarify the documentation or fix issues.