Why are we using open source software? Well that’s a rhetoric question and i am sure you come up with many reasons for that, just to name few:
- Freedom
- Quality
- Security
- Try it first
- Community
And many others. How about customizability? Have you already realized that some feature is missing in product “foo”? Fine, what now? Well try to bring the vendor to extend it. But wait, we are using open source software, right? Let’s patch it then 😉 Let’s see how easy it is … but the problem first:
$>git usage: git [--version] [--exec-path[= ]] ... The most commonly used git commands are: add Add file contents to the index branch List, create, or delete branches clone Clone a repository into a new directory [...]
So now let’s compare that output with our another favorite tool that we all so love: Gerrit:
$>ssh gerrit gerrit --help gerrit COMMAND [ARG ...] [--] [--help (-h)] [...] Available commands of gerrit are: ban-commit create-account [...]
Well, almoust identically? What about mandatory “–help” option and missing command descriptions? Yes. It is even more annoying once you extend Gerrit and create a plugin for it, like we did. Gerrit plugin typically exposes some functionality through ssh commands. And the consumer would like to know what these commands are doing. And that’s very handy to have one line description for it. Note: plugin uses the same extended documentation functionality like Gerrit code: markdown html page generation, but you still need a browser to read it. So let’s patch it upstream. It was never so easy with Gerrit: clone it, extend it and upload it to Gerrit, then wait for review. Once reviewed adjust it and wait for merging. Once it is merged, recieve congratulations for extending your favorite tool upstream 😉
$>ssh gerrit gerrit Available commands of gerrit are: ban-commit Ban a commit from a project's repo create-account Create a new batch/role account [...]
Is that the whole story? Well not really, how about manual page?
$>man gerrit-review No manual entry for gerrit-review
Hm… That would be hard, in the end we consume only ssh commands from Gerrit. And Gerrit is shipped with pretty cool documentation. OTOH that documentation is html based and we have to leave our terminal and switch to browser… really? So let’s patch that too. And create local gerrit man-pages. After deploying, it just work:
$>man gerrit-review [...]
Note: once the core Gerrit provides manual pages, the tool chain is established, it is trivial now to provide manual pages for plugins. Just copy the makefile adjust it, generate manual pages and distribute it. So, once you are using open source and missing something … go ahead and customize it 😉
Many thanks to Norbert who fisrt argued, that Gerrit is missing these features and to great Gerrit community for helping me to integrate it!
