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 [2017/10/23 16:12] rjs7evergreen-docs:how-to-contribute-documentation [2023/06/01 12:13] (current) – update branch name from master to main gmcharlton
Line 1: Line 1:
 ===== How to Contribute Documentation to the Repository ===== ===== How to Contribute Documentation to the Repository =====
  
-First of all, you are welcome to email the Documentation Listserv ([[open-ils-documentation@list.georgialibraries.org]]) with problems you find in the documentation.  However, we welcome you to participate in the process of improving things.  Below are various ways you can contribute your time and skills.+First of all, you are welcome to email the Documentation Listserv ([[evergreen-documentation@list.evergreen-ils.org]]) with problems you find in the documentation.  However, we welcome you to participate in the process of improving things.  Below are various ways you can contribute your time and skills.
  
-We use [[http://git-scm.com/|Git]] for version control on documentation. The official repository is housed on the Evergreen git server [[http://git.evergreen-ils.org/|git.evergreen-ils.org]].+We use [[http://git-scm.com/|Git]] for version control on documentation. The official repository is housed on the Evergreen git server [[http://git.evergreen-ils.org/?p=Evergreen.git;a=tree;f=docs;hb=HEAD|git.evergreen-ils.org]].
  
-**Note**: Changes to the official repository are processed into HTML, PDF and ePub nightly at 11pm. (see http://docs.evergreen-ils.org/) +**Note**: Changes to the official repository are processed into HTML daily at 1am. (see http://docs.evergreen-ils.org/)
- +
-**Note**: **The documentation is now hosted in the main Evergreen git repository:** +
-  * [[http://git.evergreen-ils.org/?p=working/Evergreen.git;a=tree;f=docs;hb=HEAD|http://git.evergreen-ils.org/?p=working/Evergreen.git;a=tree;f=docs;hb=HEAD]]+
  
 ==== Beginner workflow ==== ==== Beginner workflow ====
  
-  * Send your documentation changes in any format to the Documentation Interest Group (DIG) email list: <open-ils-documentation@list.georgialibraries.org> +  * Send your documentation changes in any format to the Documentation Interest Group (DIG) email list: <evergreen-documentation@list.evergreen-ils.org> 
-  * Valuable contributions include: corrections of typos, corrected step-by-step instructions, updated screenshots, telling us of missing sections, etc+  * **Valuable contributions include:** 
-  * Please include the following information in your email:+    * Telling us about anything that seems wrong 
 +    * Corrections of typos 
 +    * Corrected step-by-step instructions 
 +    * Updated screenshots 
 +    * Telling us of missing sections 
 +    * Etc
 +  * **Please include the following information in your email:**
     * URL of the documentation web page that needs to be updated     * URL of the documentation web page that needs to be updated
     * The part of the web page you are referring to (e.g. section heading, paragraph number, a nearby phrase, etc.)     * The part of the web page you are referring to (e.g. section heading, paragraph number, a nearby phrase, etc.)
 +
 +==== Beginner workflow with Launchpad ====
 +  * You may use Launchpad to report any errors or missing items you find in the documentation. 
 +    * Go to https://bugs.launchpad.net/evergreen/+filebug to sign up for a Launchpad account and report the problem.
 +    * Add the tag "documentation" to your report.
 +
 +
  
 ==== Intermediate workflow ==== ==== Intermediate workflow ====
  
-  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 +  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
-  * If you are creating a new file, click the //plus// symbol that displays to the right of file path.Type in the file name. {{:evergreen-docs:github-create.png}} +  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. +       PREVIEW as HTMLAny file on GitHub with the extension of ".adoc" should auto-display the HTML version of the file when previewed or saved. Then you can proofread your document and look for anything strange. 
-       Test by [[http://asciidoctor.org/docs/asciidoc-writers-guide/#where-else-is-asciidoc-rendered|creating a Gist]] and naming it ''filename.adoc''. This will display the HTML version of your file. Then you can proofread your document and look for anything strange. +       Note that there is now an automatic checker in github that will build a test copy of your docs. Instructions on that are below. 
-  * Type a message describing your change +  - Type a message describing your change 
-  Click the "Propose file change" button +  Click the "Propose file change" button 
-  One of the developers will [[evergreen-docs:github-workflow|review your change]] and send you feedback+  - Click the green "Create pull request" button 
 +  - One of the developers will [[evergreen-docs:github-workflow|review your change]] and send you feedback 
 + 
 +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 === 
 + 
 +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. 
 + 
 +To access the test build file: 
 + 
 +  - Click on an existing pull request 
 +  - Select the tab labelled "Checks" 
 +  - In the upper left, select the dropdown labelled "Artifacts" 
 +  - Click the file built-docs to download a zipped copy of the docs build 
 +  - Unzip the file and double-click on index.html in the extracted folder. This will open a preview version of the Antora docs pages in your browser. 
 +    * On Windows, the address bar will read <code>file:///C:/Users/<username>/Downloads/built-docs/docs/latest/shared/about_this_documentation.html</code> 
 +    * You can search and navigate around the docs but note that the version dropdown doesn't currently work. 
 +  - Search for the file(s) you've added or changed, and click around them to make sure everything looks and works as expected. 
 + 
 +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 <open-ils-documentation@list.georgialibraries.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 41: Line 74:
 Use these procedures on Linux, Mac OS X, or GitBash on Windows. Use these procedures on Linux, Mac OS X, or GitBash on Windows.
  
-== First time only ==+**First time only**
   - Type ''git clone git:%%//%%git.evergreen-ils.org/Evergreen.git'' to create an initial copy of the repository on your machine. This will clone the whole Evergreen repository, which contains the **docs** directory where all the documentation lives.   - Type ''git clone git:%%//%%git.evergreen-ils.org/Evergreen.git'' to create an initial copy of the repository on your machine. This will clone the whole Evergreen repository, which contains the **docs** directory where all the documentation lives.
   - ''cd Evergreen/docs'' - Moves to the new directory you just cloned.   - ''cd Evergreen/docs'' - Moves to the new directory you just cloned.
Line 53: Line 86:
  
  
-== 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
  
-After you've made your changes, make sure that your documentation is included in the appropriate manual(s).  To do this, make sure that there is a ''include::path/to/documentation.adoc[]'' statement in the appropriate ''root_*.adoc'' file (e.g. ''root_circulation.adoc'' for the circulation manual).+After you've made your changes, make sure that your documentation is included in the appropriate module(s).  To do this, make sure that there is a cross reference statement like ''%%**%% xref:acquisitions:acquisitions_search.adoc[Acquisitions Search]'' in the appropriate ''nav.adoc'' file (e.g. ''docs/modules/acquisitions/nav.adoc'' for the Acquisitions module).
  
-Then test to make sure that the docs build correctly.  The following examples use the Circulation manual, but you will want the filename ''root_circulation.adoc'' to match the manual you are trying to test.+Then **test building the various output formats**.  The following examples use the Circulation manual, but you will want the filename ''root_circulation.adoc'' to match the manual you are trying to test.
  
   - ''asciidoc root_circulation.adoc'' - Converts AsciiDoc text files to HTML format.  This will give you errors if the AsciiDoc format is incorrect.  Once it succeeds, verify that the HTML appears as you expect.  Finally, delete the output files (e.g. ''rm *.html'') to prevent them from being committed along with your AsciiDoc files.   - ''asciidoc root_circulation.adoc'' - Converts AsciiDoc text files to HTML format.  This will give you errors if the AsciiDoc format is incorrect.  Once it succeeds, verify that the HTML appears as you expect.  Finally, delete the output files (e.g. ''rm *.html'') to prevent them from being committed along with your AsciiDoc files.
   - ''%%a2x --fop root_circulation.adoc%%'' - Converts AsciiDoc text files to PDF format. Verify that the PDF appears as you expect.  Finally, delete the output files (e.g. ''rm *.pdf'') to prevent them from being committed along with your AsciiDoc files.   - ''%%a2x --fop root_circulation.adoc%%'' - Converts AsciiDoc text files to PDF format. Verify that the PDF appears as you expect.  Finally, delete the output files (e.g. ''rm *.pdf'') to prevent them from being committed along with your AsciiDoc files.
-  - ''a2x -f=epub root_circulation.adoc'' - Converts AsciiDoc text files to ePub format. Once it succeeds, delete the output files (e.g. ''rm *.epub'') to prevent them from being committed along with your AsciiDoc files.+  - ''%%a2x --format=epub root_circulation.adoc%%'' - Converts AsciiDoc text files to ePub format. Once it succeeds, delete the output files (e.g. ''rm *.epub'') to prevent them from being committed along with your AsciiDoc files. 
 + 
 +=== Build the Evergreen Documentation site locally === 
 + 
 +**This allows you to "see" your changes as presented/integrated into the full site with Evergreen's look and feel** 
 + 
 +  * More details located in the Evergreen code repository: docs/README.adoc 
 +  * Be sure and have Node installed. see [[https://github.com/nvm-sh/nvm#installation-and-update|Installing Node]] 
 +  * Once Node is installed, follow the Antora prereqs. Summarized from [[https://docs.antora.org/antora/2.3/install/linux-requirements/|Antora pre-reqs]] 
 +  * Now run generate_docs.pl 
 + 
 + 
 +^           generate_docs.pl options          ^^ 
 +| base-url | URL where html output is expected to be available eg: http://localhost | 
 +| tmp-space | Writable path for staging the antora UI repo and build files, defaults to ./build | 
 +| html-output | Path for the generated HTML files, defaults to ./output | 
 +| antora-ui-repo | Antora-UI repository for the built UI | 
 +| antora-version | Version of antora to use for build, defaults to 2.3 | 
 + 
 +  * Example: 
 +<code> 
 +$ cd Evergreen/docs 
 +$ ./generate_docs.pl 
 +--base-url http://localhost/prod \ 
 +--tmp-space ../../tmp \ 
 +--html-output /var/www/html/prod \ 
 +--antora-ui-repo git://git.evergreen-ils.org/eg-antora.git \ 
 +--antora-version 2.3 
 +</code> 
 + 
 +  * To view the site perfectly, you will need to have a web server running on your computer. 
 + 
  
 When you are satisfied with your changes, commit the files. When you are satisfied with your changes, commit the files.
Line 77: 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''
  
 If you are committing a change that somebody else made: If you are committing a change that somebody else made:
-  - ''git commit -s --author="Firstname Lastname <email@domain.com>"''+  - ''%%git commit -s --author="Firstname Lastname <email@domain.com>"%%''
   - Add a commit message that begins with "Docs:"   - Add a commit message that begins with "Docs:"
 +
 +If you try to push your change, but somebody has changed the Evergreen in the repo in the meantime, you will get this error:
 +
 +<code>
 +error: failed to push some refs to 'https://git.evergreen-ils.org/REPOSITORY.git'
 +To prevent you from losing history, non-fast-forward updates were rejected
 +Merge the remote changes (e.g. 'git pull') before pushing again.  See the
 +'Note about fast-forwards' section of 'git push --help' for details.
 +</code>
 +
 +If this happens, you just have to run ''git pull --rebase'', which should bring in the latest changes and put your commit on top.  After this, you can just repeat your ''git push'' command.
 +
  
 === Graphical tool version === === Graphical tool version ===
Line 91: Line 168:
 These procedures are recommended if you are not comfortable with the command line.   These procedures are recommended if you are not comfortable with the command line.  
  
-== First time only ==+**First time only**
   - Install one of these recommended programs: http://git-scm.com/downloads/guis   - Install one of these recommended programs: http://git-scm.com/downloads/guis
   - Start the program. Look for something like "Clone Existing Repository". In "Source", put ''git:%%//%%git.evergreen-ils.org/Evergreen.git''; leave "Target" blank to use the default path, or enter something else (it creates a new directory, so don't use one that exists already). Click Clone.   - Start the program. Look for something like "Clone Existing Repository". In "Source", put ''git:%%//%%git.evergreen-ils.org/Evergreen.git''; leave "Target" blank to use the default path, or enter something else (it creates a new directory, so don't use one that exists already). Click Clone.
  
-== Every time ==+**Every time**
   - Start your graphical git tool. Open the Evergreen repository you cloned earlier.   - Start your graphical git tool. Open the Evergreen repository you cloned earlier.
   - Select: Remote -> Fetch From -> origin   - Select: Remote -> Fetch From -> origin
Line 104: 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 <open-ils-documentation@list.georgialibraries.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.1508789544.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.