Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision |
evergreen-docs:github-workflow [2020/08/18 10:53] – aneiman | evergreen-docs:github-workflow [2023/12/28 15:34] – aneiman |
---|
When someone [[evergreen-docs:how-to-contribute-documentation#intermediate_workflow|submits a change via GitHub]], an Evergreen developer should follow these steps to review it: | When someone [[evergreen-docs:how-to-contribute-documentation#intermediate_workflow|submits a change via GitHub]], an Evergreen developer should follow these steps to review it: |
| |
- If you haven't yet, add the main Evergreen repo (on GitHub) as a remote | ===== Reviewing the pull request ===== |
| |
| - [[https://github.com/login|Log in to Github]] |
| - Open the pull request in the Github web interface. |
| - Open the Files Changed tab |
| - Make sure the asciidoc changes look good |
| - Open the Checks tab |
| - Expand the "Generate Docs Package" step. Glance for any unexpected warnings or errors. |
| - Open the Artifacts menu and select built-docs |
| - Unzip the artifact and open it in your browser. |
| - 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: |
| |
| - On the commits tab, note how many new commits are in the pull request -- you will need this information later. |
| - 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) |
- ''%%git remote add github-evergreen https://github.com/evergreen-library-system/Evergreen.git%%'' | - ''%%git remote add github-evergreen https://github.com/evergreen-library-system/Evergreen.git%%'' |
- Update your local master branch to reflect any changes from "origin" | - Update your local main branch to reflect any changes from "origin" |
- ''git checkout master; git fetch origin; git pull origin master'' | - ''git checkout main; git fetch origin; git pull origin main'' |
- Fetch the pull request branch into a new local branch | - Fetch the pull request branch into a new local branch |
- ''git fetch github-evergreen pull/[PULL_REQ_NUMBER]/head:[BRANCHNAME]'' | - ''git fetch github-evergreen pull/[PULL_REQ_NUMBER]/head:[BRANCHNAME]'' |
- Checkout your new pull request branch | - Cherry pick the relevant commits into your local copy of the main branch. |
- ''git checkout [BRANCHNAME]'' | - If only one commit: ''git cherry-pick -s [BRANCHNAME]'' |
- Rebase the pull request branch to master, and handle any conflicts | - 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%%'' |
- ''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'' | - The ''%%--edit%%'' flag will permit you to edit all commit messages as they come in. |
- Test build the changed AsciiDoc file + the root*.adoc files that include it | - If you need to squash commits: |
* ''asciidoc -a icons -a toc -d book -o OUTPUT_FILE ASCIIDOC_FILE'' | - Verify that you are in your local branch. |
* Ignore warnings for not finding any image files, but be sure to review any included images on GitHub before committing them | - If your branch is already built on current main, you can use: ''git rebase -i HEAD~2'' (where 2 is the number of commits you wish to combine) |
* 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") | - Your text editor will open and should show both of the commits, for example: |
* Docs images belong in ''Evergreen/docs/media/'' | - pick [COMMIT HASH 1] [COMMIT MESSAGE 1] |
* Also look for other AsciiDoc warnings or errors | - pick [COMMIT HASH 2] [COMMIT MESSAGE 2] |
| - Change the word "pick" in the second line to "fixup" then save and close the file |
| - squash --> merges commits, then allows amendment of commit message |
| - fixup --> merges commits like squash does, but discards previous commit message |
| - Check gitlog to ensure that you now have a single commit |
- Make any corrections (via additional commits, if needed) | - Make any corrections (via additional commits, if needed) |
- Use ''git log'' to retrieve commit IDs | - Use ''git log'' to make sure everything looks good. |
- Use interactive rebase to add the commits to your local master, adding your sign-off | - Make sure that the commit message begins with "Docs:" |
- ''git checkout master'' | - Make sure the commit message includes the relevant Launchpad bug number |
- ''git cherry-pick [commit ID]'' | - Example: "Resolves LP#1234567" |
* Include the relevant Launchpad bug number somewhere in the commit message | - (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>"%%'') |
* Example: "Resolves LP#1234567" | - When you are confident your local main branch is ready: ''git push origin main'' |
* (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>"%%'') | |
- When you are confident your local master branch is ready: ''git push origin master'' | |
- Backport to previous EG versions as appropriate | - Backport to previous EG versions as appropriate |
- Email docs list and/or pull requester to say it is done (or with other feedback) | - ''git checkout rel_3_8'' (where rel_3_8 is the branch for previous version) |
- Close pull request on GitHub | - ''git pull'' (to get the most up-to-date version of the branch) |
| - If one commit: ''git cherry-pick main'' |
| - If more than one: ''git cherry-pick main~[Number of commits]..main'' |
| - ''git push'' |
| - Go back to the pull request on Github's site. Comment on the pull request to thank the contributor, then close the pull request. |