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:

Reviewing the pull request

  1. Open the pull request in the Github web interface.
  2. Open the Files Changed tab
  3. Make sure the asciidoc changes look good
  4. Open the Checks tab
  5. Expand the "Generate Docs Package" step. Glance for any unexpected warnings or errors.
  6. Open the Artifacts menu and select built-docs
  7. Unzip the artifact and open it in your browser.
  8. Check to make sure that the expected changes look good in the built docs, and that there are no unexpected changes.

Committing the changes

If everything looks good:

  1. On the commits tab, note how many new commits are in the pull request – you will need this information later.
  2. In your terminal, 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
  3. Update your local master branch to reflect any changes from "origin"
    1. git checkout master; git fetch origin; git pull origin master
  4. Fetch the pull request branch into a new local branch
    1. git fetch github-evergreen pull/[PULL_REQ_NUMBER]/head:[BRANCHNAME]
  5. Cherry pick the relevant commits into your local copy of the master branch.
    1. If only one commit: git cherry-pick -s [BRANCHNAME]
    2. If more than one: git cherry-pick -s [BRANCHNAME]~[Number of commits]..[BRANCHNAME] --edit (for example, if you are bringing in two commits from the survey-docs branch, run git cherry-pick survey-docs~2..survey-docs) --edit
      1. The --edit flag will permit you to edit all commit messages as they come in.
  6. Make any corrections (via additional commits, if needed)
  7. Use git log to make sure everything looks good.
    1. Make sure that the commit message begins with "Docs:"
    2. Make sure the commit message includes the relevant Launchpad bug number
      1. Example: "Resolves LP#1234567"
    3. (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>")
  8. When you are confident your local master branch is ready: git push origin master
  9. Backport to previous EG versions as appropriate
    1. git checkout rel_3_8 (where rel_3_8 is the branch for previous version)
    2. git pull (to get the most up-to-date version of the branch)
    3. If one commit: git cherry-pick master
    4. If more than one: git cherry-pick master~[Number of commits]..master
    5. git push
  10. Go back to the pull request on Github's site. Comment on the pull request to thank the contributor, then close the pull request.
evergreen-docs/github-workflow.txt · Last modified: 2022/05/12 09:23 by sandbergja

© 2008-2022 GPLS and others. Evergreen is open source software, freely licensed under GNU GPLv2 or later.
The Evergreen Project is a U.S. 501(c)3 non-profit organization.