Git bz configuration

Git bz requires python 3 
Optionally, if you plan on sending bugs to Bugzilla from git, you'll need to tell it your username and password or if you have Chrome or Firefox installed on your dev machine, and have logged into Bugzilla at least once from that machine, git-bz can use that. 
= Get ready =
 If you are using koha-testing-docker, git-bz is already available from inside the container and you need only set your `.env` as described in the k-t-d documentation.
If you wish to use git-bz from your host or you are not using koha-testing-docker then please continue. All commands should be run locally and not in the k-t-d shell.
== Download git-bz ==
In your home directory, run: 
 git clone https://gitlab.com/koha-community/git-bz.git
 cd ~/git-bz
== Configure git-bz ==
Symlink git-bz somewhere that's in your $PATH. For example, 
 sudo ln -s ~/git-bz/git-bz /usr/local/bin/git-bz
will often work. To check the contents of your $PATH, run 
echo $PATH
This will give you a colon separated list of all directories that are included in your $PATH variable. You might need to add /usr/local/bin/ to your path if it is missing. To do that edit ~/.bash_profile with your favourite editor and add :/usr/local/bin to the path using the command below. (If you're using the terminal in your virtual machine's desktop environment use ~/.profile instead of ~/.bash_profile.) 
 PATH=$PATH:/usr/sbin:/usr/bin:/usr/local/bin
 export PATH
(An alternative to symlinking and adding /usr/local/bin/ to your path is simply to add the filepath to your git-bz file to your $PATH. To find the correct filepath you can use the commands below.) 
cd ~/git-bz
pwd
PATH=$PATH:filepath (the result of pwd)
export PATH
 
Run the command below to enable these changes in your terminal session. Alternatively you can close your terminal window and open a new one. 
source ~/.bash_profile
 
Then navigate to the directory that contains your clone of the Koha source code repository e.g. 
 cd ~/git/koha
run: 
 git config bz.default-tracker bugs.koha-community.org
 git config bz.default-product Koha
 git config --global bz-tracker.bugs.koha-community.org.path /bugzilla3
 git config --global bz-tracker.bugs.koha-community.org.https true
 git config --global core.whitespace trailing-space,space-before-tab
 git config --global apply.whitespace fix
If you don't mind storing your Bugzilla credentials in your config files, run the following commands replacing U with your Bugzilla username and PW with your Bugzilla password (if you have not yet created a Bugzilla account then you will need to before completing this step). 
 git config --global bz-tracker.bugs.koha-community.org.bz-user U
 git config --global bz-tracker.bugs.koha-community.org.bz-password PW
These are --global to avoid keeping your username and password in the clear in the repository, but keeping them in your global .gitconfig isn't great either.
If you don't want to store your password in your config files, use git-credential
 git config --global credential.helper 'cache --timeout 3600' # timeout in seconds
 git config --global credential.https://bugs.koha-community.org.username U
 git config --global bz-tracker.bugs.koha-community.org.use-git-credential true
again replacing U with your Bugzilla username and PW with your Bugzilla password. You need to set your user name and password (or setup git-credential) regardless of whether or not you intend to upload patches using git-bz (FIXME: is this a bug?). 
Now you are ready to do some work with git-bz
= Using git-bz =
Check out a branch where xxxxx is your bug number: 
 git checkout -b bug_xxxxx origin/main
=== Bugs with one patch ===
==== Submitting a patch ====
This command simply attaches the last commit to the listed bug -- no need to git format-patch 
 git bz attach xxxxx HEAD
With -e, allows editing of the attachments on the listed bug -- obsoleting old attachments, etc. (This operation can time out rather quickly, if you get a "traceback" from Python try once more and be quicker.) 
 git bz attach -e xxxxx HEAD
*HEAD attaches the last commit to the bug.
==== Testing ====
Apply a patch from Bugzilla 
 git bz apply xxxxx
<Test it> 
You can apply the patches interactively [i] if you want to change the order or only apply certain patches.
==== Signing off ====
If you're signing off on a patch and want to attach the signed off patch to the bug you can use: 
 git commit --amend -s 
or 
 git so X 
if there are more than one patch (see #Bugs with more than one patch below), e.g. 
 git so 2
and then: 
 git bz attach -e xxxx HEAD
or
 git bz attach -e xxxx HEAD~X..
if there are more than one patch (see #Bugs with more than one patch below), e.g. 
 git bz attach -e xxxx HEAD~2..
for two patches
The -e option will let you edit the bug report attributes. It is handy to switch the status to Signed Off.
If you forgot, it's time to open your bug in Bugzilla using the http://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=xxxxx URL and change the bug's status to Signed Off
=== Bugs with more than one patch ===
==== Getting the patches ====
If a bug has more than one patch, you can still get all of them the same way as described above: 
 git bz apply xxxx
This will walk you through all the patches and let you choose which ones you want to apply. 
==== Signing off ====
If you are signing off more than one patch (after testing them, of course) you can do this: 
 Put the following alias in your .git/config file: 
 [alias]
 so = "!f() { git rebase --interactive --exec 'git commit --amend --signoff --no-edit' HEAD~$1; }; f"
 This alias is already defined if you are using a koha-testing-docker
Until you have this alias defined, you can sign off the number of patches you want with the following git command: 
 git so X
where X is the number of patches to sign-off
==== Attaching patches ====
Now it's time for attaching the patches to the bug.
To attach the last X patches, run:
 git bz attach -e xxxxx HEAD~X..HEAD
Since the last HEAD is not mandatory (if missing it will default to HEAD), this command is similar to:
 git bz attach -e xxxxx HEAD~X..
So if you have 2 patches to attach, you can do this with:
 git bz attach -e xxxxx HEAD~2..
Uncomment the # before each patch you would like to obsolete before saving. You will have to be pretty fast here, if you dawdle git bz will bring back a nasty error, but you can simply rerun the command (making your edits faster this time) to avoid it.
To specify a more complex range of commits, see gitrevisions(7) for details.
== Sponsorship ==
If you've forgotten to add a "Sponsored-by: Awesome Sponsor" line to your patches, and you're dreading going back and adding it commit by commit, you can always do a batch update!
 git rebase --exec 'git commit --amend --trailer "Sponsored-by: Awesome Sponsor" --no-edit' HEAD~2
== Documentation ==
Full documentation can be found at http://git.fishsoup.net/man/git-bz.html 
= Troubleshooting =
== No patch applied ==
So, you have a bug, and type something like: 
 dpavlin@koha-dev:/srv/kohaclone$ git bz apply 7161
 Bug 7161 - Open Library - Larger image, Read, borrow and checked-out status
and nothing happens after it? It's quite possible that bug doesn't have patch attached. 
Or, if it does have file attached (which you can see under attachments) it might have application/octet-stream type instead of patch. Go into details > Edit details and check patch checkbox. 
Now git-bz will work as expected: 
 dpavlin@koha-dev:/srv/kohaclone$ git bz apply 7161
 Bug 7161 - Open Library - Larger image, Read, borrow and checked-out status
 
 Open Library - Larger image, Read, borrow and checked-out status
 Apply? [yn] y
 
 Applying: Bug-7161 Open Library - Larger image, Read, borrow and checked-out status
== Reset branch to clean main ==
Abort application of patches from e-mail 
 git am --abort
Remove all local changes and revert your checkout to clean upstream main 
 git reset --hard origin/main
 
== git bz attach -e timeout ==
If you are not fast enough git bz attach -e might time-out on you with a long python stack trace similar to this: 
 dpavlin@koha-dev:/srv/koha_ffzg$ git bz attach -e 7161 HEAD
 Traceback (most recent call last):
 File "/usr/local/bin/git-bz", line 2142, in <module>
 do_attach(*args)
 File "/usr/local/bin/git-bz", line 1622, in do_attach
 attach_commits(bug, commits, edit_comments=global_options.edit)
 File "/usr/local/bin/git-bz", line 1572, in attach_commits
 bug.create_patch(description, body, filename, patch, obsoletes=obsoletes, status=status)
 File "/usr/local/bin/git-bz", line 1188, in create_patch
 response = self.server.send_post("/attachment.cgi", fields, files)
 File "/usr/local/bin/git-bz", line 948, in send_post
 return self.send_request("POST", url, data=body, headers={ 'Content-Type': content_type })
 File "/usr/local/bin/git-bz", line 884, in send_request
 response = connection.getresponse()
 File "/usr/lib/python2.6/httplib.py", line 990, in getresponse
 response.begin()
 File "/usr/lib/python2.6/httplib.py", line 391, in begin
 version, status, reason = self._read_status()
 File "/usr/lib/python2.6/httplib.py", line 355, in _read_status
 raise BadStatusLine(line)
 httplib.BadStatusLine
To fix it, just re-try the command and it should work. 
== Known bugs ==
#--mail option can't send to other recipients - maybe should have a repository-specific configuration option? 
#default statuses aren't the default Bugzilla ones - maybe the koha-community ones should be added by a repository-specific configuration option and maybe activated automatically if it sees bugs.koha-community.org in use? 
#not possible to apply patches without -3 - should have a config or option to suppress it. 
#only handles ASCII characters in commit message
== Known problems ==
$ /usr/local/bin/git-bz
-su: /usr/local/bin/git-bz : /usr/bin/python : mauvais interpréteur: Aucun fichier ou dossier de ce type
$ ls /usr/bin/py*
/usr/bin/pydoc2.6 /usr/bin/pygettext2.6 /usr/bin/python2.6
# ln -s /usr/bin/python2.6 /usr/bin/python
 
But if the above happens, your python installation is probably broken and you just made the problem worse if there's a package manager... 
On Ubuntu 21.10 I got his problem:
 $ git-bz attach -e HEAD 29982
 bash: /usr/local/bin/git-bz: /usr/bin/python2: bad interpreter: No such file or directory
I solved this by installing python2. 
=== For my fellow macOS users. ===
Since python2 has reached end-of-life you might install the python package from its website. Note that this installs the executable to /usr/local/bin. Therefore, after installing python2 you might still get the following error.
 fatal: 'bz' appears to be a git command, but we were not
 able to execute it. Maybe git-bz is broken?
To resolve this, change the shebang in the git-bz script to the path of your python2 installation, e.g.: 
 - #!/usr/bin/python2
 + #!/usr/local/bin/python2
This resolves the issue. 
==== ssl.SSLError ====
If you see this error message:
 ssl.SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:727)
Open Finder and go to your Applications/Python 2.7 directory and double-click the Install Certificates.command file. This should fix it. 
Category:Git