Evergreen DokuWiki

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.

We use Git for version control on documentation. The official repository is housed on the Evergreen git server 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: 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

• Send your documentation changes in any format to the Documentation Interest Group (DIG) email list: open-ils-documentation@list.georgialibraries.org
• Valuable contributions include: 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
  • The part of the web page you are referring to (e.g. section heading, paragraph number, a nearby phrase, etc.)

• Login to GitHub (or create a free account)
• Find the relevant file in the 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)
• Click the pencil ("Edit this file") icon to edit the file in your browser
• If you are creating a new file, click the plus symbol that displays to the right of file path.Type in the file name.
• Make your changes, using correct AsciiDoc format.
• Test that your AsciiDoc syntax is correct. This is not required for simple typo corrections.
  • Test by 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.
• Type a message describing your change
• Click the "Propose file change" button
• One of the developers will review your change and send you feedback

Command line (Linux, or GitBash on Windows):

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

Graphical tool (recommended if you are not comfortable with the command line)

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

1. 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.
2. Make changes to files, remove files, add new files
3. a2x FILENAME -f=epub - Converts AsciiDoc text files to other file formats (such as ePub). This will give you errors if the AsciiDoc format is incorrect. Once it succeeds, delete the output files (e.g. rm *.epub) to prevent them from being committed along with your AsciiDoc files.
4. git add - Tells git that you have added or edited files on your local machine and want to add them into the repository. The changes are not committed yet.
5. git commit path/FILENAME OR git commit path/FILENAME -m "[what you changed]" - Commits changes to the repository. A note on what you changed is mandatory. If you use the shorter form, a text editor will open (usually vim) where you will write your change note. (Using the -m switch is a time-saver if your note is short) To commit all changes, use git commit ..
6. git push - If you are one of the few DIG members with permission to push to the master repository, do so using your SSL passphrase. After pushing your changes you should see them show up at 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.

1. Start your graphical git tool. Open the Evergreen repository you cloned earlier.
2. Select: Remote -> Fetch From -> origin
3. Select: Merge -> Local Merge, and click Merge to pull the most recent changes into your cloned version. This avoids merging issues and errors when "pushing" your changes to the remote repository.
4. Use a good text editor to make changes to files or create new files.
5. Test that your AsciiDoc syntax is correct. A quick way to do this is by creating a Gist and naming it filename.adoc. Then you can proofread your document and look for anything strange.
6. Press F5 (or select Commit -> Rescan) to view the changes you have made. Files will display under Unstaged Changes (red). Click a file to see color-coded changes in the pane to the right.
7. 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.
8. 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.
9. 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.
10. 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.
11. Once your changes are pushed to master, you should see them show up in the master repository.