Hello, everyone! I am delighted to have the opportunity to work on Kart under the mentorship of Robert Coup, Craig de Stigter and Andrew Olsen for the project - Kart CLI Help Improvements as part of the Google Summer of Code. What entails is my awesome GSoC journey for the past three months 😄.
Community Bonding Period
The community bonding period is meant for GSoC contributors to get to know mentors, read documentation, and get up to speed to begin working on their projects before the coding starts. So, I had been reading the documentation for the past couple of months and fixing minor issues in Kart. Here are some of the pull requests I made:
- Make conflicts and diffs consistent - #602
- Make schema changes fail gracefully - #584
- Minor Improvements to the CLI - #588
- Add Sphinx + RTD documentation -#573
Week 1
In this week, I worked on tab completion in kart (see koordinates/kart#643 (issue)) using the python click package. There were a couple of hiccups along the way with understanding and trying to work around (or fix) how shell completion is handled in click. The mentors were very kind and helpful in proposing different ideas which helped me progress in completing these pull requests:
- Add tab completion for Kart - #644
- Add
--install-tab-completionoption for installing shell completion - #648
Week 2 - 3
Kart is aimed to be cross-platform. This includes support for Windows users. Therefore, I focused on adding Powershell tab completion during this time frame. Click doesn't have any PowerShell support for tab-completion but one can add shell completion for any shell they choose. I had to figure out how to do this with Click and integrate it into Kart with some understanding of Powershell scripting. Here is the pull request which I made to resolve this:
- Support tab completion in PowerShell for kart - #654
Week 4
Kart needed a documentation framework with a man-style page integration given that it has a CLI interface. I did some research but couldn't find any out-of-the-box implementation for supporting our use case. Since I had added Sphinx documentation to Kart earlier and given that sphinx is quite extensible, the mentors and I agreed that building a custom extension would be the way to go in order to suit the use case of Kart. I researched and analyzed requirements and started learning about custom sphinx extensions.
Week 5
I went through the tutorials on Sphinx's documentation to learn how to build custom sphinx extensions. Apart from learning how to build extensions it also taught me to appreciate what a good and extensible documentation framework is all about (Django vibes 💚). Pull requests from this week:
Week 6
I pivoted around to my proposal and figured out that using click-man would satisfy the requirements. So I added man-style pagers for Posix systems instead of click's default help page when calling --help and used click-man to generate man pages programmatically. While experimenting with click-man, I also tried using sphinx-click for generating man pages but couldn't get much out of it (see stackoverflow question). Here are the pull requests from this week:
Week 7
Most of the things this week revolved around #682. I modified it to make it compatible with Windows (using text pages) and POSIX (using man pages) and made a process flow diagram to make reviewing things easier.
#682 implements the help page rendering at runtime. The mentors and I all agreed that this is probably better suited to build-time. So I started with writing a bash/python script that builds the pages for the whole app. I also needed to consider integrating this process with the CMake build and/or Github Actions. Here are the pull requests I worked on this week:
- Add man-style help page renderers for Kart - #682
- ci: change "Date" to work with user's locale - #685
Week 8
The python script to generate a help page (man page for Posix, and text page for windows) to be run at build time was also ready to go. In order to facilitate the entire build process, I spent time learning more about CMake this week to integrate the help pages into the newer build automation (Kart used make earlier) we have at Kart.
Week 9 - 12
Continued to make more improvements to #682 by writing the python script for generating help pages and integrating it at build time using CMake. This reduced the time required for kart --help and also reduced the number of dependencies. Given that the path to the help page was now known in the newer method, I decided to use man which removes both groff and the paging part out of the equation 🙌. The paging methods used now are:
- For Windows -
click.echo_via_pager() - For POSIX -
man <path_to_page>
The new and simplified design:
I also made a few fixes for tab completion add another fix to add help pages for multilevel and hidden commands. Pull requests from this week:
- Add man-style help page renderers for Kart - #682
- tests: fix Date for commands passed to git - #694
- fix(config): move
--install-tab-completionto its own command - #703
Conclusion
Kart is one of the best code bases I have had the opportunity to contribute to. I learned a lot about SDLC, clean code and above all what good engineering leadership looks like. Koordinates has a very talented team behind it, and I had an amazing time working with them!