Git guide for documentation
From Koha Wiki
This is a beginners guide to using Git - aimed at non-developers, and specifically for the documentation team.
Download and install Git
Configuring the basic settings
Initial copy of koha-manual repository
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
- 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.
- Head: this is the last node, or change, at the top of your tree
- Merge request:
- Pull request:
Workflow for documentation
Cover normal work flow - creating a branch, working on changes, committing changes, merging into master, pushing up, merge requests...
|git checkout master||Makes sure you are on the master 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.|
Cover amending commits, resetting things, ...
To edit the last commit message:
git commit --amend
Taiga [number] ([bugzilla number]): [Short title] Short paragraph(s) that succinctly describe the change and why the change was made.
Taiga 778 (8630): Add Adlibris cover images system preferences
Taiga 760 (21380): Update image > patrons/readinghistory.png (image464)
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:
- If relevant, mention what version of Koha the change relates to, for example: new system preference added to 19.05
Add (follow-up) or (DM follow-up) to the title, for example:
Taiga 779 (14222): (DM follow-up) Update OpacShowHoldQueueDetails system preference
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.
Other tutorials and resources
- Koha developers guides for Git:
- Create visual guide and cheat sheet, example: https://www.git-tower.com/learn/cheat-sheets/git