Google-Summer-of-Code-2020-Work-Product-Submission.md

+# Overview
+
+- [x] Basic functionality by the end of first month
+  - [x] Services support
+  - [x] Sockets support
+  - [x] Timers support 
+- [x] Testing with units installed on a Debian buster system
+  - [x] Services
+  - [x] Sockets
+  - [x] Timers
+- [x] Documentation
+  - [x] Manpage
+  - [x] Usage
+  - [x] Comments
+- [ ] Debian
+  - [ ] Package
+  - [ ] Integration
+
+# Ideas
+
+## Portability
+
+The translator should work across all Linux systems. This meant having as few
+external dependencies as possible and making use of the language's native
+features. A great choice for something like this would be `C` but because the
+trade-off for lines of code is huge. Something like `bash` which is available on
+most linux systems was a great alternative choice. On systems like Alpine Linux
+too which default to an alternative shell, `bash` can easily be installed.
+
+## Simplicity
+
+The code should be readable first and efficient next. A block spanning across
+multiple lines that has a singular purpose but is readable would be preferred
+over an one-liner that does multiple things.
+
+## Maintainability
+
+The project is not / will not be limited to me as an author. The idea of
+open-source is that multiple people benefit from it and also be able to
+contribute to it with ease. Explanations are spread across blocks of code,
+laying out, with examples, what a particular piece of code does.
+
+# Challenges
+
+## Filtering can be complicated
+
+[This
+commit](https://salsa.debian.org/kayg/systemd-unit-translator/-/commit/1a1419a085f94827b0f43efb63997e53b4ced185)
+introduces the filtering logic for INI formatted files. It looks simple but
+makes use of multiple tools and fails when there are multiple `=` characters.
+[This
+commit](https://salsa.debian.org/kayg/systemd-unit-translator/-/commit/70408540a7da834143d035a5b762aa15ad84d992)
+fixes that completely and logic works 100% of the time but at the cost of
+simplicity, and adding another dependency which is not installed by default on a
+Debian Buster system - `gawk`. Finally, [this
+commit](https://salsa.debian.org/kayg/systemd-unit-translator/-/commit/766bedee8d4a3a33ae590b0eb752fa306f576820)
+introduces a simple, straightforward logic that does not depend on any external
+tools.
+
+## Path resolution
+
+Often the script will get invoked from arbitrary locations and will be given
+arbitrary paths as arguments. Commits like
+[this](https://salsa.debian.org/kayg/systemd-unit-translator/-/commit/0642bc42eeb833b822f7fed028509e7d7d9da520)
+and
+[this](https://salsa.debian.org/kayg/systemd-unit-translator/-/commit/9ade7b52f32e00f5f3b0f8b3e45730bb6ddd72b1)
+make sure that the paths are always converted to their absolute equivalents and
+then filtered or processed.
+
+## Feature disparity
+
+Systemd is a monolith and boasts a lot of features in one tool. To replicate
+similar functionality, one tool was not always enough. To translate socket
+functionality, both `xinetd` and `socket-activate` [had to be
+used](https://salsa.debian.org/kayg/systemd-unit-translator/-/commit/977260107829877c65ad25d27e543534184024b6)
+as `xinetd` is not capable of filesystem sockets.
+
+## Calendar events
+
+Perhaps the biggest challenge was the timers section of the project which is
+also the place where the [most complicated
+code](https://salsa.debian.org/kayg/systemd-unit-translator/-/commit/b98552f9d21ec74db7ffb00d78fb3219e9cfd797)
+can be seen. It's because calendar events can be specified in a [lot of
+different
+ways](https://www.freedesktop.org/software/systemd/man/systemd.time.html). To
+handle those cases, heavy use of regular expressions was done. This is likely to
+be either simplified in the future or a real parser would be used. The former is
+preferred as long as the code gets simplified and remains readable.
+
+# Future
+
+- Integration with the OpenRC Debian package which could not be completed during
+  the coding period. This would facilitate easy and automatic translation of
+  to-be-installed packages that come with systemd units.
+  
+- Continuous Integration which automates testing of each commit with a variety
+  of units and generates a report with error messages and debug logs.
+  
+- Bugfixes, issues and any improvements that will be made over the course of time.
+
+# Last Words
+
+I am grateful to [Adam Borowski](https://salsa.debian.org/kilobyte), [Benda
+Xu](https://salsa.debian.org/heroxbd-guest) and [Mo
+Zhou](https://salsa.debian.org/lumin) for being extremely patient and helpful
+throughout this period. It has been a great summer and more importantly, an
+absolutely great learning-while-working experience.