User Tools

Site Tools


evergreen-docs:github-workflow

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
evergreen-docs:github-workflow [2017/09/27 09:03] rjs7evergreen-docs:github-workflow [2023/12/28 15:54] (current) aneiman
Line 1: Line 1:
 ====== Docs GitHub Workflow ====== ====== 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%%''     - ''%%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'' +      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 branchenter ''git rebase -i HEAD~2'' (where 2 is the number of commits you wish to combine)     
-    * Ignore warnings for not finding any image filesbut be sure to review any included images on GitHub before committing them +    - Your text editor will open and should show both of the commitsfor example: 
-      * NOTE: You need to download and add the docs images into the git branchif they aren'in the branch already (e.g. if the images are posted in the GitHub "conversation") +      - ''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 fileThis merges the commits and retains the first line's 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 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   - 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.
evergreen-docs/github-workflow.1506517415.txt.gz · Last modified: 2022/02/10 13:34 (external edit)

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki

© 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.