Introduction

This is a beginners guide to using Git - aimed at non-developers, and specifically for the documentation team.

Initial setup

Download and install Git

See https://git-scm.com/downloads and https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

Configuring the basic settings

Initial copy of koha-manual repository

Key concepts

Git is a version control system. That means that all the change history of a file is kept and you can go back to an earlier version at any time.

Visually, you can think of git as a tree, with nodes where all the changes are. The last node is called the "head".

The other main characteristic of Git is that it allows for collaborative work because it has a local/remote structure (think server/client of the old days).

Cover purpose of versioning, branches and commits.

Insert visual diagram to illustrate

Glossary

Branch:
Clone:
Fork: this is when you take a project and copy it into your own remote repository to make a parallel project. From there, you can take your fork in a totally different direction from the original project, or continue to pull and merge from the original project to keep your fork up-to-date.

A fork creates two parallel projects, just like a fork in a tree creates two trees

Head: this is the last node, or change, at the top of your tree
Merge request:
Origin:
Pull request:
Remote:
Repository:

Workflow for documentation

Cover normal work flow - creating a branch, working on changes, committing changes, merging into main, pushing up, merge requests...

Git workflow for a normal change to the manual
Command	Description
git checkout main	Makes sure you are on the main branch.
git pull	Makes sure you have the latest changes.
git checkout -b taiga-XXXX-short-title	Create a new branch for the documentation task you are working on.
Write and make changes!	Use your preferred editor to make changes. Examples of editors include: atom.io
git add .	Adds changed files ready to commit.
git commit	Record the changes you have made - see commit message guidelines.
..	..

Fixing mistakes

Cover amending commits, resetting things, ...

To edit the last commit message:

 git commit --amend

Commit messages

Taiga [number] ([bugzilla number]): [Short title]

Short paragraph(s) that succinctly describe the change
and why the change was made.

Subject line

 Taiga 778 (8630): Add Adlibris cover images system preferences

 Taiga 760 (21380): Update image > patrons/readinghistory.png (image464)

Description

The main aim here is to explain what has changed and why.

If you skim read the commit message you should get a good idea of what was changed without needing to look at the diff for the change.

The release notes text in Bugzilla provides a useful summary as a starting point for the commit message.

Some standard examples:

Update to System preferences > Enhanced content (systempreferences.rst). Adds new ... introduced in Koha 19.05.
Updated images.rst to remove two images no longer used:
- source/images/admin/...

Notes:

If relevant, mention what version of Koha the change relates to, for example: new system preference added to 19.05

Follow-ups

Add (follow-up) or (DM follow-up) to the title, for example:

 Taiga 779 (14222): (DM follow-up) Update OpacShowHoldQueueDetails system preference

Examples

 Taiga 787 (11911): Add note about suggestions_manage permission
 
 Update to Acquisitions > Managing suggestions (acquisitions.rst) to add
 a note about the new manage purchase suggestions (suggestions_manage)
 permission added in 18.11.

 Taiga 778 (8630): Add Adlibris cover images system preferences
 
 Updates System preferences > Enhanced content with the Adlibris system
 preferences. This enhancement was added in Koha 18.11 and allows
 libraries to use cover images from Swedish book retailer Adlibris.

Show recent commits

You can see the details of all recent commits with the log command:

$ git log

To get a summary of all recent commits:

$ git log --oneline

For detailed guidelines on writing commit messages for Koha see Commit messages.

To do

Create visual guide and cheat sheet, example: https://www.git-tower.com/learn/cheat-sheets/git

Git guide for documentation

Contents