Docs GitHub Workflow

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

1. Log in to Github
2. Open the pull request in the Github web interface.
3. Open the Files Changed tab
4. Make sure the asciidoc changes look good
5. Open the Checks tab
6. Expand the "Generate Docs Package" step. Glance for any unexpected warnings or errors.
7. Open the Artifacts menu and select built-docs
8. Unzip the artifact and open it in your browser.
9. Check to make sure that the expected changes look good in the built docs, and that there are no unexpected 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 (make sure you're in the directory you're working on before running command)
   1. git remote add github-evergreen https://github.com/evergreen-library-system/Evergreen.git
3. Update your local main branch to reflect any changes from "origin"
   1. git checkout main && git fetch origin && git pull origin main
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 main 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. If you need to squash commits:
   1. From your local branch, enter git rebase -i HEAD~2 (where 2 is the number of commits you wish to combine)
   2. Your text editor will open and should show both of the commits, for example:
      1. pick [COMMIT HASH 1] [COMMIT MESSAGE 1]
      2. pick [COMMIT HASH 2] [COMMIT MESSAGE 2]
   3. Change the word pick in the second line to fixup then save and close the file. This merges the commits and retains the first line's commit message.
   4. Check gitlog to ensure that you now have a single commit
7. Make any corrections (via additional commits, if needed)
8. 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>")
9. When you are confident your local main branch is ready: git push origin main
10. 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 main
    4. If more than one: git cherry-pick main~[Number of commits]..main
    5. git push
11. Go back to the pull request on Github's site. Comment on the pull request to thank the contributor, then close the pull request.