Page Comparison

...

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:

   

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

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

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

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

   Image Added

   In this case:

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

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

      Image Added

   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:

      Image Added

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…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:
   

   Image Removed

   . 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.]You can add more detail in the extended description, and you’ll also have a chance later to add more detail.
   

   Image Added

8. Click “Propose changes”. [TODO: compare changes page: green for new, red for removed. only shows sections you changed]. 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: [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.

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. [TODO: they may not be able to request a review.]Click “Create pull request”. 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 . You with your changes, a check might fail. If this happens, you don’t have to delete the pull request. Go 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,

       Image Added

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

    file.

    1. File:

       Image Added

    2. Edit file, and Commit changes

    . Commit

    1. again. When given the choice, choose to commit directly to the

    patch-1 branch

    1. exiting branch.

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