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. If you are using -i, git will open your preferred text editor, where you can indicate which commits you'd like to squash.
  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 git log to retrieve commit IDs
  9. Add the commits to your local master, adding your sign-off
    1. git checkout master
    2. git cherry-pick -s [commit ID]
      • Include the relevant Launchpad bug number somewhere in the commit message
        • Example: "Resolves LP#1234567"
      • (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>")
  10. When you are confident your local master branch is ready: git push origin master
  11. Backport to previous EG versions as appropriate
  12. Email docs list and/or pull requester to say it is done (or with other feedback)
  13. Close pull request on GitHub
evergreen-docs/github-workflow.txt · Last modified: 2020/08/18 10:59 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.