User Tools

Site Tools


evergreen-docs:how-to-contribute-documentation

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:how-to-contribute-documentation [2022/04/04 15:07] – [Automatic build checker] aneimanevergreen-docs:how-to-contribute-documentation [2023/06/01 12:13] (current) – update branch name from master to main gmcharlton
Line 31: Line 31:
  
   - Login to GitHub (or create a free account)   - Login to GitHub (or create a free account)
-  - Find the relevant file in the [[https://github.com/evergreen-library-system/Evergreen/tree/master/docs|GitHub repository]]+  - Find the relevant file in the [[https://github.com/evergreen-library-system/Evergreen/tree/main/docs|GitHub repository]]
     * Look around until you find the content (note: the directories are mostly logically similar to the online docs table of contents sections, but may require some searching around)     * Look around until you find the content (note: the directories are mostly logically similar to the online docs table of contents sections, but may require some searching around)
-  - Click the pencil ("Edit this file") icon to edit the file in your browser *OR* If you are creating a new file, click the Add File button. Type in the file name.+  - Click the pencil ("Edit this file") icon to edit the file in your browser **OR** If you are creating a new file, click the Add File button. Type in the file name. Make sure you are in the correct directory.
   - Make your changes, using [[http://powerman.name/doc/asciidoc|correct AsciiDoc format]].   - Make your changes, using [[http://powerman.name/doc/asciidoc|correct AsciiDoc format]].
   - **Test that your AsciiDoc syntax is correct.** This is not required for simple typo corrections.   - **Test that your AsciiDoc syntax is correct.** This is not required for simple typo corrections.
Line 44: Line 44:
  
 A variation of this workflow is described [[https://youtu.be/XiVjO_S0Y-s|in this YouTube video]]. A variation of this workflow is described [[https://youtu.be/XiVjO_S0Y-s|in this YouTube video]].
 +An alternative of the above workflow using GitHub Desktop is [[https://docs.evergreen-ils.org/eg/docs/latest/shared/how_to_contribute_docs.html|here]]
  
-===== Automatic build checker =====+=== Automatic build checker ===
  
 As of 2021, Evergreen's github repository contains a tool that will build a full Antora-ized copy of the docs whenever someone opens a github pulllrequest that includes documentation changes. You can download this copy and view it in your browser to make sure things like image files and internal links are operating correctly. As of 2021, Evergreen's github repository contains a tool that will build a full Antora-ized copy of the docs whenever someone opens a github pulllrequest that includes documentation changes. You can download this copy and view it in your browser to make sure things like image files and internal links are operating correctly.
Line 60: Line 61:
   - Search for the file(s) you've added or changed, and click around them to make sure everything looks and works as expected.   - Search for the file(s) you've added or changed, and click around them to make sure everything looks and works as expected.
  
-{{:evergreen-docs:built-docs_1_.gif?direct&400|}}+Click on the image below to see a screencast of this process (credit: Jane Sandberg) 
 + 
 +{{:evergreen-docs:built-docs_1_.gif?direct&200|}}
  
  
 ==== Advanced workflow ==== ==== Advanced workflow ====
  
-This workflow is primarily for the few DIG members with permission to push to the master repository. If you do not have permission yet, you can start the request process by contacting the Git Admins group <gitadmin@evergreen-ils.org>. You can also push to another public repository, such as the Evergreen working repository or another host such as GitHub.  Then email the DIG email list <evergreen-documentation@list.evergreen-ils.org> with the location of your repository so they can pull your changes into master.+This workflow is primarily for the few DIG members with permission to push to the primary community repository. If you do not have permission yet, you can start the request process by contacting the Git Admins group <gitadmin@evergreen-ils.org>. You can also push to another public repository, such as the Evergreen working repository or another host such as GitHub.  Then email the DIG email list <evergreen-documentation@list.evergreen-ils.org> with the location of your repository so they can pull your changes into main.
  
 === Command line version === === Command line version ===
Line 85: Line 88:
 **Every time** **Every time**
   - ''%%git fetch --all%%''   - ''%%git fetch --all%%''
-  - ''git checkout master''+  - ''git checkout main''
   - ''git pull'' - Pulls the most recent changes into your cloned version. This avoids merging issues and errors when "pushing" your changes to the remote repository.   - ''git pull'' - Pulls the most recent changes into your cloned version. This avoids merging issues and errors when "pushing" your changes to the remote repository.
   - Make changes to files, remove files, add new files   - Make changes to files, remove files, add new files
Line 139: Line 142:
       * has a signoff       * has a signoff
  
-After you have committed to master+After you have committed to main
   - ''git checkout [BRANCH]'' - you will probably also want to add your change to the documentation for all relevant versions.  For example, if you are documenting a feature that was added to version 3.2, you will want to add it to the 3.2 documentation.  Release branches are in the form ''rel_3_2'', so for our example, you would type ''git checkout rel_3_2''.   - ''git checkout [BRANCH]'' - you will probably also want to add your change to the documentation for all relevant versions.  For example, if you are documenting a feature that was added to version 3.2, you will want to add it to the 3.2 documentation.  Release branches are in the form ''rel_3_2'', so for our example, you would type ''git checkout rel_3_2''.
   - ''git pull'' - if this branch has changed since the last time you ran this command.   - ''git pull'' - if this branch has changed since the last time you ran this command.
-  - ''git cherry-pick [NUMBER OF COMMIT]'' - if you didn't note the number of the commit, run ''git checkout master; git log -3'' to find it.  Then be sure to return to this branch with ''git checkout [BRANCH]''.+  - ''git cherry-pick [NUMBER OF COMMIT]'' - if you didn't note the number of the commit, run ''git checkout main; git log -3'' to find it.  Then be sure to return to this branch with ''git checkout [BRANCH]''.
   - ''git push''   - ''git push''
  
Line 178: Line 181:
   - With your changed files highlighted, click "Stage Changed" to tell Git you want to add the changes to the repository. The changes are not committed yet. Files will display under the green "Staged Changes" section.   - With your changed files highlighted, click "Stage Changed" to tell Git you want to add the changes to the repository. The changes are not committed yet. Files will display under the green "Staged Changes" section.
   - To commit (a step that confirms your intention to make changes to the public repository), first type a note on what you changed in the "Commit Message" box. **A note is mandatory.** Then click the "Commit" button.   - To commit (a step that confirms your intention to make changes to the public repository), first type a note on what you changed in the "Commit Message" box. **A note is mandatory.** Then click the "Commit" button.
-  - Finally, push your changes to the remote repository by clicking "Push." A dialog box will open with the default settings (source branch master, remote origin). Click "Push". If you are one of the few DIG members with permission to push to the master repository, you will need to enter your SSL passphrase. If you do not have permission yet, you can start the request process by contacting the Git Admins group <gitadmin@evergreen-ils.org>. You can also push to another public repository, such as the Evergreen working repository or another host such as GitHub.  Then email the DIG email list <evergreen-documentation@list.evergreen-ils.org> with the location of your repository so they can pull your changes into master+  - Finally, push your changes to the remote repository by clicking "Push." A dialog box will open with the default settings (source branch main, remote origin). Click "Push". If you are one of the few DIG members with permission to push to the main repository, you will need to enter your SSL passphrase. If you do not have permission yet, you can start the request process by contacting the Git Admins group <gitadmin@evergreen-ils.org>. You can also push to another public repository, such as the Evergreen working repository or another host such as GitHub.  Then email the DIG email list <evergreen-documentation@list.evergreen-ils.org> with the location of your repository so they can pull your changes into main
-  - If you get "Error: Command Failed," changes may have been made by someone else since you last pulled a copy of the master file. The text in the box will say that "non-fast-forward updates were rejected." Click Close, do a fetch and merge (or a pull, which does both), and push again. +  - If you get "Error: Command Failed," changes may have been made by someone else since you last pulled a copy of the main branch. The text in the box will say that "non-fast-forward updates were rejected." Click Close, do a fetch and merge (or a pull, which does both), and push again. 
-  - Once your changes are pushed to master, you should see them show up in the [[http://git.evergreen-ils.org/?p=Evergreen.git;a=tree;h=refs/heads/master;hb=refs/heads/master|master repository]].+  - Once your changes are pushed to main , you should see them show up in the [[http://git.evergreen-ils.org/?p=Evergreen.git;a=tree;h=refs/heads/main;hb=refs/heads/main|primary community repository]].
  
  
evergreen-docs/how-to-contribute-documentation.1649099262.txt.gz · Last modified: 2022/04/04 15:07 by aneiman

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.