5. Submit a Documentation Pull Request

Commit & Push (Sync) Changes (Git)

You should commit and sync your changes at least daily to ensure there's a backup of your work. 
It is a good practice to limit each commit to a set of changes made for a single reason. Making frequent, smaller commits that have clear descriptions makes it easier to troubleshoot and deal with rebasing conflicts.

Command Line

  1. (optional) Type git status to see which files have changed.
  2. (optional) If some of the files that you've worked on are not staged for commit, type git add <file name> to add them.
    • Shortcut: You can type git add <folder> to add all files in that folder, or git add -A to add all the files you've changed at once.
  3. Type git commit -m "<commit message>", where <commit message> is a description of your changes (50 or fewer characters).
  4. Type git push --set-upstream origin <branch name>.

GitHub Desktop

  1. With your working branch selected, GitHub Desktop displays changes you have made that have not yet been committed ("Uncommitted Changes").
  2. Under Uncommitted Changes, enter a brief summary of your changes in the Summary field; optionally, enter more information about your changes in the Description field.
  3. Click Commit to commit your changes, and then click Sync.

Create a Pull Request (GitHub on the Web)

When you're ready for work to be reviewed, create a pull request. You can create a pull request from the GitHub Desktop, but it's recommended that you create a pull request with GitHub on the web via the process below, so that you can use the preformatted template to include needed information, such as reviewers, for the pull request.

  1. After you sync your changes on GitHub Desktop or "push" your latest commit using the command line, go to https://github.com/edx/edx-documentation.
    Near the top of the page, you see a "You recently pushed branches" message, along with the name of your branch and a green Compare & pull request button. 
  2. Select Compare & pull request.
  3. On the page that opens, enter a descriptive name for the pull request, and then fill in the template. GitHub sends e-mail messages to anyone you tag.
  4. (Optional) Copy the URL for your pull request and paste it into a comment in the related JIRA story.

Optional: Produce HTML for Reviewers

For reviewers who don't have a GitHub account or to provide an easier reading experience to reviewers, you can create an HTML version of your branch and circulate a link. Most SMEs will review your RST file in GitHub on the web.

See Publish Documentation on Read the Docs for instructions on preparing an HTML draft.

NOTE: Make sure you create your own new draft Read the Docs project, rather than building a new version of the existing published guide.