Differences

This shows you the differences between two versions of the page.

--- evergreen-docs:github-workflow [2014/12/12 14:49] – rjs7
+++ evergreen-docs:github-workflow [2023/12/28 15:51] – aneiman
@@ Line 1: / Line 1: @@
 ====== Docs GitHub Workflow ======
-When someone [[evergreen-docs:how-to-contribute-documentation#quick_start_for_new_contributors|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%%''
-  - 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
     - ''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''
+      - The ''%%--edit%%'' flag will permit you to edit all commit messages as they come in.
-  - Test build the changed AsciiDoc file
+  - If you need to squash commits:
-    * ''asciidoc -a data-uri -a icons -a toc -d book -o OUTPUT_FILE ASCIIDOC_FILE''
+    - From your local branch, enter ''git rebase -i HEAD~2'' (where 2 is the number of commits you wish to combine)
-    * Ignore warnings for not finding any image files, but be sure to review any included images on GitHub before committing them
+    - Your text editor will open and should show both of the commits, for example:
-    * Also look for other AsciiDoc warnings or errors
+      - pick [COMMIT HASH 1] [COMMIT MESSAGE 1]
+      - 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)
-  - Use interactive rebase to add the commits to your local master, adding your sign-off
+  - Use ''git log'' to make sure everything looks good.
-    - ''git checkout master''
+    - Make sure that the commit message begins with "Docs:"
-    - ''git rebase -i [BRANCH_NAME]^'' (note the caret!)
+    - Make sure the commit message includes the relevant Launchpad bug number
-      * Include the relevant Launchpad bug number somewhere in the commit message
+        - Example: "Resolves LP#1234567"
-        * 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>"%%'')
-      * Out-dent the sign-off line (if present)
+  - When you are confident your local main branch is ready: ''git push origin main''
-      * 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>"%%'')
-  - When you are confident your commits are ready: ''git push origin master''
   - 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.