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:

   

   TODO: “You need to fork this repo to propose changes”. Click “Fork this repository.”

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

   

   Note: shared pages: copy the ../.. line. click the en_us word in the blue breadcrumbs. Navigate down to the included page. Click the pencil.

4. 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….]

5. 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, but it will have a Commit message:
   

   

6. 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. [TODO: Move this before the picture] [TODO: Say something about extended description.]

7. Click “Propose changes”. [TODO: compare changes page: green for new, red for removed. only shows sections you changed]. This take you to a page to create a pull request. This is GitHub’s term for a proposed change: [TODO: if this is your first PR, you are invited to review contribution guidelines and code of conduct.]
   

   

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

8. You will need someone to review your change. Use the Reviewers section in the right sidebar to select a reviewer. [TODO: they may not be able to request a review.]

9. Click “Create pull request”. 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.

10. If there are problems. You don’t have to delete the pull request. Go to the Files Changed tab, … menu, Edit file. Commit changes. Commit directly to the patch-1 branch.