Starting in Catalyst Koha team

This will be a guide for new employees starting in Koha Team, and is currently a Work in Progress.
So you've joined the Koha Team? Awesome! This is the guide to get you started.
== The Koha Team ==
You can keep contact with the Koha team using the #koha IRC chat, useful to get access to this early in case you run into problems setting up your environment. Useful IRC chats to have around are:
* The Koha Community #koha at irc.oftc.net:6667
== Koha Documentation ==
* The Koha Website
* Community Developers Page
* The Koha Manual
* The Koha Wiki
* Koha on Github
* The Koha System Database
== Parts of Koha ==
There are a lot of parts that make up the Koha System, a full list of which you can find on Bugzilla. The main parts you will probably be concerned about are the following:
* The OPAC - This stands for "Online Public Access Catalogue" it's the online version of Koha which corresponds to http://localhost:8080/ on your local instance and http://demo.mykoha.co.nz/ on the Catalyst Demo Koha. The perl scripts that provide the functionality of these pages are located in your /home/vagrant/kohaclone/opac/* folder in your KohaDevBox Vagrant instance.
* The Intranet or Staff Interface - This is the part of Koha only accessible to staff which includes administration tools. This corresponds to http://localhost:8081/ in your local instance and http://demo-intra.mykoha.co.nz/ on the Catalyst Demo Koha. The perl scripts that provide the functionality of these pages are located throughout your /home/vagrant/kohaclone/* folder in your KohaDevBox Vagrant instance.
== Setting up your Development Environment ==
*Set up a Koha Bugzilla Account 
*Install VirutalBox using
 sudo apt-get install VirtualBox
*Install Git 
*Install Vagrant 
*Install Ansible 
*Clone and set up your KohaDevBox 
*Once your KohaDevBox has been installed and initialised, change directory to the kohadevbox directory and use the "vagrant up" command to set up your VM. This can take a while!
 vagrant up
 vagrant ssh
*Inside your KohaDevBox VM, install git bz
 
==== Setting Up Vim for Coding Perl ====
*http://wiki.koha-community.org/wiki/Vim 
*http://wiki.koha-community.org/wiki/Debugging_in_VIM
 
==== Common installation errors ====
There are several errors which can happen when you run the vagrant up command: 
a) (Optional) try vagrant up (it may throw an error requiring you to install Ansible again, if it does throw an error type in the following): 
git clone git://github.com/ansible/ansible.git –recursive 
b) (Optional) If it throws an error saying there is an issue with VBoxManage and the error is in the VagrantFile simply run the following command in the kohadevbox directory: 
git checkout 40e52a0b4c055f90b1811fe2af8415e0e5a18772 
This is rolling back the branch to a commit where we know that the kohadevbox will work. 
c) (Optional)If it says there is a issue with VT-d visualisation not enabled in the BIOS, restart the machine and press enter to bring up the BIOS, go to security->Visualisation and set both settings to [Enabled], as the issue is your BIOS is not enabling visualisation. 
d) (Optional) When loading the intranet and/or OPAC if it just continues to load, check the intranet-error.log with this command:
tail -f /var/log/koha/kohadev/intranet-error.log 
If it shows an error like this: 
[Fri Sep 29 00:43:02.523371 2017] [proxy_http:error] [pid 17602] (70007)The timeout specified has expired: [client 10.0.2.2:37034] AH01102: error reading status line from remote server httpd-UDS:0 
[Fri Sep 29 00:43:02.523461 2017] [proxy:error] [pid 17602] [client 10.0.2.2:37034] AH00898: Error reading from remote server returned by /index.html
What it is doing is Apache thinks that Plack is running when it isn't so what you need to do is check the Apache config and make sure it is actually disabled and then restart apache and try loading the localhost:8081 again. 
When running through the Web installer and it asks you that Perl modules are misssing and that you need to install them write in this command to get the correct Mojolicious version:
sudo cpanm -i Mojolicious::Plugin::OpenAPI@1.15
And write in the command for the other two Perl modules:
sudo cpanm <perl_module_name> 
== Tools and Processes in Koha Development ==
It is important to become familiar with the Koha Coding Guidelines and Koha Development Workflow
==== Updating Koha ====
Ensure you keep your Koha up to date by regularly running the following in your kohaclone in vagrant. Koha updates often, so it's a good idea to run these weekly to stay with the latest version.
 git fetch
 git checkout origin/main
==== Resetting the Koha database ====
If you need to reset your Koha database for whatever reason, you can use the following set of commands in your Kohadevbox vagrant instance to do so.
Make sure your Koha codebase is up to date:
 git fetch
 git checkout origin/main
Back up your current database in case anything goes wrong. The default value for <instancename> is kohadev.
 sudo koha-dump <instancename>
Get your debian-sys-maint user credentials for the next step
 sudo cat /etc/mysql/debian.cnf
Delete the Koha database (and enter the password from the above command when prompted):
 mysqladmin -u debian-sys-maint -p drop koha_kohadev
Create the Koha database (and enter the password from the above command when prompted):
 mysqladmin -u debian-sys-maint -p create koha_kohadev
Go to the staff login page in your browser and go thorough the web installer:
 http://localhost:8081/
If you would like to add sample catalogue data to your database, now is a good time to follow the guide on that, a bit further down the page :)
 Load sample data (optional)
Reindex your Koha database
 sudo koha-rebuild-zebra -f -v kohadev
==== Testing and Signing Off Koha Patches ====
* Signing Off Patches on Koha Wiki
A good way to familiarise yourself with the different parts of Koha and how they work is to test and sign off patches for bug fixes. A quick guide to using git bz to apply and sign off patches can be found on the git bz configuration page under using git bz, a more detailed walk-through is provided below.
# Go onto the Bugzilla home page in your browser and click the 'search' button next to 'browse'. 
# This will take you to a Basic Search form, click the link for Advanced Search right beside it. 
# Under the 'Status' drop down menu, choose 'Needs Signoff', and then go to the bottom of the page and click Search.
#: The difficulty of each entry depends on your knowledge of how to reproduce the bug and what it takes to test, so for a start you will be limited by your knowledge of the system. A good place to start is to go back to the Advanced Search, and selecting the "Staff Client" option, then see if you can find one dealing with changes to messages or text.
# When you click on a bug it will take you to a page with lots of information about it
#: Alias, product, version, hardware, you don't need to play around with, they're important for documentation mostly, but aren’t really relevant to our testing.
#: Version is important, it tells you which version of Koha the bug is in, this should almost always be main.
#: Status is where the bug is at, so a newly reported bug will be called NEW, if someone submits a patch to fix it the status becomes Needs Signoff. When someone tests it and it works this becomes Signed Off, if it doesn't work then it Fails QA or Patch doesn't apply, depending on the error message. If it gets signed off, a higher team looks at it and it Passes QA, before being Pushed to Stable where it will be integrated in the next version release.
# Scroll down to the bottom of the page and open the attachment. This should have all the instructions for testing the bug.
# Carry out the testing. 
#: To access your Koha as a client would, use http://localhost:8080/ for Public interface and http://localhost:8081/ for the Staff interface.
#: If you need credentials to log in you can find them in the file located in /etc/koha/sites/<instance_name>/koha-conf.xml in the KohaDevBox VM.
# To apply a patch, use the following command: 
#: git bz apply <bug_number> 
# If you are happy to sign off on the patch (it works as expected according to the test plan) then use the following command:
#: git commit --amend -s
# Now an editor will come up with your information already filled out, you can safely save and exit the file.
#: If it opened in Nano you can use CTRL + W followed by CTRL + X to save and escape. In VIM you can use :wq followed by enter.
# Use the following command:
#: git bz attach -e <bug_number> HEAD
# Your editor will open again, this time you need to uncomment the "Signed Off" status by moving the cursor down and removing the "#" in front of the line that says "# Signed Off"
#: If it opened in Nano you can use CTRL + W followed by CTRL + X to save and escape. In VIM you can use :w then enter followed by :q and enter again.
# Check that it worked by going back to your browser and refreshing the bug page!
# Finally always do a "git checkout origin/main" before testing a new patch!
==== Checking Koha Warns ====
"Warns" are helpful debugging messages Koha uses to tell you what's going wrong in the system. To access these messages, there are two very helpful commands you can run from the kohadevbox (if you aren't running the kohadevbox, replace it with the name of your instance):
 sudo koha-shell kohadev
This will likely generate two error messages:
* bash: cannot set terminal process group (-1): Inappropriate ioctl for device
* bash: no job control in this shell
You can safely ignore both these error messages. Next run either this command for intranet related errors:
 tail -f /var/log/koha/kohadev/intranet-error.log
Or alternatively this one for OPAC related errors:
 tail -f /var/log/koha/kohadev/opac-error.log
This shows the 10 latest lines of the error.log file. It updates live so you can see any warnings or errors as they are produced while using Koha in your browser.
==== Loading Sample Data into Koha ====
For many tests you may need sample data (books and such) to work with. Loading the database with books yourself can be time consuming and also requires some specialist knowledge. Lucky for us there are files with catalogue data pre-prepared and readily available.
* Available MARC files containing sample catalogue data 
** 500 Classics as Ebooks MARC file
** Miscellaneous catalogue items, inc books/audio/etc. Right click and select File > Save As
* Instructions on how to load MARC files into Koha using the staff interface
* Instructions on how to import uploaded MARC file batches to the public catalogue
==== Patching Koha ====
Check out the Koha Community Git Guide!
When creating fixes and enhancements for Koha you should:
* Create the bug in Bugzilla first if it does not exist yet.
* Create a new branch in git referencing the bug name before making any additions or changes.
* Ensure you write good commit messages.
How to Write a Good Commit Message:
* http://wiki.koha-community.org/wiki/Commit_messages
* http://git.catalyst.net.nz/gw?p=koha.git;a=commit;h=47be5cafefbd7841e6792d0d0dede654f3afff96
Creating and Submitting your Patch:
* http://wiki.koha-community.org/wiki/Version_Control_Using_Git#Update_your_git_install_of_Koha
== Enchancements and Patching Bugs ==
* Official Koha Bug Reporting Guidelines
* Official Koha Patch Submitting Information