This page describes a lightweight way for anyone to make changes to pages they find in the edX or Open edX documentation. The original source for our docs are stored as ReStructured Text (.rst) files on GitHub. Changes are suggested using GitHub pull requests.

TODO: edX vs Open edX and differences between the two.

Prerequisites

You will need a GitHub account.

You will need to be onboarded as an Open edX contributor. [TODO: explain this. Link]

You will need to be logged in to GitHub.

Editing a page

1. Find the page you want to change. Navigate to the published page you want to change, for example starting from https://docs.openedx.org or https://docs.edx.org.

2. In the upper-right is a GitHub icon. Click it to get a drop-down menu, and select “Suggest edit” from it:

   Open

   

    

3. If you see a page that says “You need to fork this repo to propose changes”, go ahead and click “Fork this repository.”

4. This will take you to a page on GitHub with an editor for the .rst file:

   Open

   

    

5. If the editor only shows one line starting with .. include::, it will look like this:

   In this case:

   1. Copy line 1 to get the file path starting with “shared”

   2. In the blue breadcrumbs, click “en_us”:

   3. You’ll be navigating within the repository. Scroll down to click into the “shared” folder, then continue navigating to find the .rst file indicated by the .. include:: line you started with.

   4. You will end up at a rendered view of the .rst file. Click the pencil tool in the upper-right to edit the file:

6. Edit the page in that editor to make your changes. This might involve details of .rst sytnax, cross-references, and so on. [TODO: Link to resources explaining rst syntax etc….]

7. When you are ready, click the green “Commit changes…” button in the upper right. It will present you with a form to fill out. Your form may have fewer fields than this picture, but it will have a Commit message. The commit message should be like an email subject line. What did you change? Commit messages start with a prefix indicating the type of change. For content changes, use “docs:” as the prefix. You can add more detail in the extended description, and you’ll also have a chance later to add more detail.
   
   

    

8. Click “Propose changes”. This will take you to a page summarizing the changes you made. New text is highlighted in green and removed text is in red. Only the changed sections of the file are shown. Click “Create pull request.”

9. This take you to a page to create a pull request. This is GitHub’s term for a proposed change:
   
   

   You can add more detail to the description of the changes, including links to supporting materials, and so on.

10. Click “Create pull request”.

11. You will need someone to review your change. Use the Reviewers section in the right sidebar to select a reviewer. If you can’t select a reviewer, copy the URL to the pull request, and get in touch with them separately.

12. Now the bottom of the pull request page will have a number of checks:
    
    

    The readthedocs.org checks are the most useful. When they are done running, the Details links on the right will take you to readthedocs to see how your changes will actually publish.

13. If there are problems with your changes, a check might fail. If this happens, you don’t have to delete the pull request. You can edit your file and the pull request will automatically be updated with the changes:

    1. In the pull request, go to the Files Changed tab, … menu,

        

    2. Find the file you need to fix, and from the dot-dot-dot menu, select Edit File:

        

    3. Edit file, and Commit changes again. When given the choice, choose to commit directly to the exiting branch.

    4. Refresh the pull request page to see the latest changes.