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. However, we will continue to use the github repository for authoring and editing documentation since it provides more editing options and a few extra features.

Note: Changes to the github documentation will be added to the official repository (git.evergreen-ils.org) and processed into HTML and PDF nightly at 11pm.

Note: The documentation is now hosted in the main Evergreen github repository (github.com/evergreen-library-system/Evergreen), rather than the repositories mentioned below.

1. Set up a free github account
2. Send an email to the repository maintainer (ysuarez@berklee.edu) to request being added as a contributor

Editing files directly in github using the following procedures is not recommended for larger changes, but is useful for quick typo corrections and other minor edits. Please be extra-careful to keep the XML formatting valid, as a mistake can prevent the chapter from updating (don't touch any tags)! If you need to make major changes, either install git on your own machine (directions follow), or send changes to the DIG list.

1. Go to the github repository at https://github.com/evergreen-library-system/Evergreen
2. Choose the docs folder
3. Navigate to the file you would like to edit and click Edit this file
4. Make changes, enter your change notes in the Commit message box and click Commit Changes
5. Submit a “pull request” to the Evergreen bug tracker on Launchpad
   • Include your GitHub commit URL in the message
   • Add “documentation” in the tags

• On Linux
• On Windows
• On Mac (OSX)

Command line (Linux, or GitBash on Windows): Type git clone git@github.com:ysuarez/Evergreen-DocBook.git to create an initial copy of the repository on your machine. You will need to enter your SSH passphrase.

GitGui on Windows (recommended if you are not comfortable with the command line): On launch, click Clone Existing Repository. In “Source”, put git@github.com:ysuarez/Evergreen-DocBook.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. You will be prompted for your SSH passphrase.

Note: If you get an error message with the git@github.com clone source, use git://github.com/rsoulliere/Evergreen-DocBook.git instead. Then edit the config file in the .git directory (top level of your cloned repository, ie Evergreen-DocBook) and change the value for url (in the [remote “origin”] section) to git@github.com:ysuarez/Evergreen-DocBook.git.

1. Change to the working directory (Evergreen-DocBook).
2. 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.
3. Make changes to files, remove files, add new files… Note: if adding a new file (chapter), its presence must be indicated in root.xml of the appropriate branch (book).
4. Verify that all changed files still validate as correct XML/DocBook syntax. The docBook files are generated every night to update the HTML and PDF files. Incorrect DocBook syntax could cause the chapter to be skipped during processing and not be included in the documentation.
5. 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 commited yet.
6. 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, you will be put into a text editor (usually vim) to compose your note. (Using the -m switch is a time-saver!) To commit all changes, use git commit ..
7. git push - Push your changes to the remote repository. After pushing your changes you should see them show up at https://github.com/ysuarez/Evergreen-DocBook/commits/master.

1. Launch GitGui. Click on Evergreen-DocBook under “Open Recent Repository.”
2. First, select Remote → Fetch From → origin, then 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.
3. Use your choice of XML editor to make changes to files or create new files. Note: if adding a new file (chapter), its presence must be indicated in root.xml of the appropriate branch (book).
4. Verify that all changed files still validate as correct XML/DocBook syntax. The docBook files are generated every night to update the HTML and PDF files. Incorrect DocBook syntax could cause the chapter to be skipped during processing and not be included in the documentation.
5. Press F5 (or select Commit → Rescan) to view the changes you have made. Files will disply under Unstaged Changes (red). Click a file to see color-coded changes in the pane to the right.
6. With your changed files highlighted, click “Stage Changed” to tell Git you want to add the changes to the repository. The changes are not commited yet. Files will display under the green “Staged Changes” section.
7. 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.
8. 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”. You will need to type your passphrase.
9. 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, and push again.
10. After pushing your changes you should see them show up at https://github.com/ysuarez/Evergreen-DocBook/commits/master.