The little talked about stress of Open Source project release management…
So I really enjoy writing code. Been doing it for years, since I was 8! I still do it now when work needs me to, or in my less than copious free time.
The problem I tend to find on these projects is that you can make them as simple or as complex as you like. This can be a curse and a blessing.
For me it tends to be a curse.
The Curse of Helping People
I want to create Products – yes Open Source API should be thought of as Products – that people want to use. This means adding useful and common functionality.
What I tend to do is have a few features I know I need for my work, and add those in. I then add features that are obvious next steps. So on my MarkLogic C++ API, for example, I’ve added support for all document types – XML, JSON, text and binary – even though I tend to just use JSON and XML.
I then occasionally receive feature requests from people. I add these to a list and try to add them as and when I need to. Batch document upload was one such example.
The upshot of all this is that there’s a lot of individual features that wind their way in to each scheduled release. All the while I’m doing this in my free time for the most part. (The features not, strictly, needed for my day job anyway).
The Curse of Documentation
Other developers desperately need good documentation. We’re all schooled about how important it is. I actually personally rather enjoy writing good technical documentation.
But you never schedule enough time for it, do you? Doesn’t matter how hard you try.
For this release I had to write a document (install, quick start, language specific info) for each of the four languages I now support. I also created a decent sized developers guide.
Then I created install instructions for each platform – how to get files, and where to put them.
Then I had to make sure the instructions worked! And not just on MyMachine[™]!
I then had to worry about formatting, re-use, images, and so on.
I’m still not happy with the API documentation. It’s quite sparse, and doesn’t have any examples embedded within it, unlike the excellent cppreference.com website.
I’d also prefer to have videos rather than just writing, but those take extra time to create and edit, and you need to have done the written one and tested it first anyway – so it takes twice the effort.
But it all DOES need doing. Any project that says they don’t need better docs is doomed to failure as developers roll their own or move on to other projects with better docs and support.
The Curse of Perfection
There are internal processes in MarkLogic for quality around open source projects. They’re quite basic so as not to be onerous, but are good best practice.
There are also a bunch of extra things I do because I’m an OCD Solution Architect who has to have a bigger tick list than absolutely necessary, because I want everyone to love my work.
This caused me to spend an awful lot more time testing, developing, and re-testing than should have been necessary. The API is cross platform, so I’ve tested on Mac, Windows 10, Ubuntu and CentOS 7.
Once you find a big-ish problem though and fix it, you kinda have to go back and re-test the other platforms again too!!! So you end up doing three times the amount of platform testing than you expected.
Also you have to write tests for the new functions and re-run them. I’m not a fan of test driven development – it leads to crappy APIs that make no sense to app developers – I prefer to start with a sample app rather than a test. Subtle change, but important.
Sample driven development means writing apps based on my APIs requires less code as I tend to write a bunch of common helper methods for you. A prime example was with BatchUpload where instead of just taking a DocumentSet, I also provided a helper function to recursively go through a folder and populate a DocumentSet. If you had done this in Test Driven Development, I doubt you’d see the need to write a helper method for your app developers. Same goes for convenience methods in classes.
Then of course you have the inevitable bugs from your tests and platform testing – these are NOT reflected in the issues list on GitHub as you quickly find them before they appear in the develop branch, and thus they are fixed in the ‘add this new enhancement’ issue rather than a bug or regression report.
How big a curse
Here’s what the above ended up looking like from a feature / GitHub issues perspective:-
- Planned feature enhancements: 32
- Bug fixes: 8
- Documentation: 7
- Code quality: 10
- Testing: 4
- Release creation/installers/packages: 9
- Total: 70
Doesn’t sound like a lot – but bear in mind I had the chance to write maybe 20% of the API during work hours this time around as I needed it for my day job, much more than normal, and it still took 5 months to do!
Notice especially how ‘new features’ – typically the main thing you spend time thinking about before scheduling work for a release – takes up less than 40% of the actual issues logged.
Self Discipline (aka The Plan)
I have a cunning plan. So cunning you could debug Western Scotland with it…
I’m going to reduce the total number of issues per release to just 30. This makes it more targeted.
I’m also going to only plan one third for new features. This allows me more for bug fixes, documentation, and ‘ease of use’ – i.e. installers and such like – features. I’ll also add new issue types for each category of item.
So MLC++ 8.0.3 and MarkLogic Workflow 8.0.3 will look like this:-
- 8 new features MAX
- 5 bug fixes
- 5 documentation work items
- 4 testing
- 2 code quality enhancements
- 6 release work items
- Total: 30
This should increase quality but minimise stress.
Hopefully it will also allow the frequency of releases to increase, but that’s very much a secondary objective.
Primarily I want to create a better quality release with just a few new features to keep people coming back regularly. I also want to make it very easy to use, thus working on installers and documentation more.
Wish me luck! I’ll post with what I find!
Adam's Deep Technology Blog 