User Tools

Site Tools


evergreen-docs:github-workflow

Docs GitHub Workflow

When someone submits a change via GitHub, an Evergreen developer should follow these steps to review it:

  1. If you haven't yet, add the main Evergreen repo (on GitHub) as a remote
    1. git remote add github-evergreen https://github.com/evergreen-library-system/Evergreen.git
  2. Update your local master branch to reflect any changes from "origin"
    1. git checkout master; git fetch origin; git pull origin master
  3. Fetch the pull request branch into a new local branch
    1. git fetch github-evergreen pull/[PULL_REQ_NUMBER]/head:[BRANCHNAME]
  4. Checkout your new pull request branch
    1. git checkout [BRANCHNAME]
  5. Rebase the pull request branch to master, and handle any conflicts
    1. git rebase master – note: if you are planning to squash multiple commits into a single commit, this is a good time to do it by running this command with the -i flag, i.e. git rebase -i master
  6. Test build the changed AsciiDoc file + the root*.adoc files that include it
    • asciidoc -a icons -a toc -d book -o OUTPUT_FILE ASCIIDOC_FILE
    • Ignore warnings for not finding any image files, but be sure to review any included images on GitHub before committing them
      • NOTE: You need to download and add the docs images into the git branch, if they aren't in the branch already (e.g. if the images are posted in the GitHub "conversation")
      • Docs images belong in Evergreen/docs/media/
    • Also look for other AsciiDoc warnings or errors
  7. Make any corrections (via additional commits, if needed)
  8. Use interactive rebase to add the commits to your local master, adding your sign-off
    1. git checkout master
    2. git rebase -i [BRANCH_NAME]^ (note the caret!)
      • Include the relevant Launchpad bug number somewhere in the commit message
        • Example: "Resolves LP#1234567"
      • Out-dent the sign-off line (if present)
      • Add newlines to long commit messages, making lines about 72 characters long
      • (If the GitHub author does not match the author's identity in git.evergreen-ils.org, consider fixing it with git commit --amend --author="NAME <email>")
  9. When you are confident your local master branch is ready: git push origin master
  10. Backport to previous EG versions as appropriate
  11. Email docs list and/or pull requester to say it is done (or with other feedback)
  12. Close pull request on GitHub
evergreen-docs/github-workflow.txt · Last modified: 2018/12/06 12:34 by sandbergja

© 2008-2017 GPLS and others. Evergreen is open source software, freely licensed under GNU GPLv2 or later.
The Evergreen Project is a member of Software Freedom Conservancy.