Going to Bitbucket

20 May 2018
I have had a Bitbucket account for some time, but it was not something I used for personal projects — I only used it for web-based projects I did with my brother and a few others some years ago. Recently I decided to move my open-source projects into public repositories, in short because they were capable of presentation & cross-referencing source code in a way that my own websites could not compare with without expending an unrealistic amount of effort. This was important as a major reason for maintaining source code online was to show-case it, rather than just make it “available” online.

Outsourcing presentation

The move towards Bitbucket started with the firmware I wrote as part of various electronics projects, as the source code was de-facto already open-sourced, but the way it was done proved problematic. Some articles included the entire source code verbatim in a single block, whereas others somewhat artificially broke down the firmware into sub-functions that were spread throughout the article. Neither approach was ideal, and it involved a significant amount of effort. Starting with the 17-segment LCD display I decided I was better off hosting the source code on a service that is specialised for the task — it allowed the code to be properly presented complete and in-context whereas I could still refer back to specific lines of code on an as-needed basis without flooding articles with large blocks of inline code.

Living projects

A problem with putting firmware source code into articles themselves is that the firmware in effect becomes frozen — updating it requires significant effort, and in general I prefer articles to be mostly immutable. Putting firmware code into a repository rather than the article itself has the advantage in that it allows the article and code development to progress separately, and in particular allows easy post-publication updates to the source code. With the 17-segment LCD project the display routines were complete but the I2C interface had yet to be implemented, so having the code in a repository allowed completion of the firmware without holding back publication of the article. A more important thing is correcting minor mistakes, such as one I made at one point with a circuit that used a PIC12F1822 microcontroller: The firmware was setting _LVP_OFF (Low-voltage programming off) within Configuration Word 1, when it is actually a part of Configuration Word 2 — this was inadvertently setting _FCMEN_OFF (Fail-safe Clock Monitor off) instead. For the circuit in question this made no difference, but it would cause problems in other circuits: _MCLRE_OFF requires _LVP_OFF, which has caught me out in the past.

Moving across historic projects

Having decided to host firmware on Bitbucket, it was not much of a leap to decide to move across other open-source projects I had released in the past. Most of them are only really still online as a show-case of sorts, and these days people expect a web-based view rather than having to download tarballs. In most cases the content of the mini-site associated with each piece of software amounted to what could easily be consolidated into a single markdown readme file: A brief-ish introduction, usually a screenshot, some details regarding run-time dependencies, and a download page. At least with Bitbucket, short descriptions don't seem out of place in the same way as they do with custom project websites.

Base of repository reconstruction

Although most (if not all) the projects used version control when first developed, I opted to instead reconstruct repositories from the tarball releases, in effect limiting the source code release to what I had already decided should be public. Since I was not interested in making the day-to-day history of the development public, a conversion of the Subversion repositories would end up being substantially more effort for much the same end result.

Code and documentation cleanup

As a general rule the resulting head of each project repository represents the most recent release tarball, because in most cases the projects are ones I do not have any interest in maintaining. The conversion of the mini-websites into a README.md did involve minor changes, but this was mainly to take account of the different presentation. The one big exception was SSI.cgi, which was by far the hardest project to move across — the main difficulty was it being the one project that included a lot of material on its mini-website, with much of it making fancy use of HTML & CSS.

Open-sourcing the lot

Three of my software projects were closed-source, and originally I was going to leave then alone due to lack of build environments, but in the end I open-sourced two of them because I felt there would be little point keeping them online otherwise. I no longer felt any need to keep the source code secret, and in fact would probably never even look at the source code again if it remained that way. However opening up the source code was not straightforward:
SprigFern
SprigFern had a varied development history, but the version that I released was built using MonoDevelop, so I used a clean install within a freshly deployed Fedora 28 instance. Although very little of the program logic was changed — removal of loading unused icons and changing outdated contact information — the project solution file had to be recreated and a lot of dead code was stripped out. In hindsight the cleaned-up project is my best open-source program, coming complete with unit tests.
D-Hondt calculators
These are various standalone election result calculatos that are associated with my dedicated D'Hondt website, and hence were only linked to from this website, so for expedience I left then out of this round of migrations. The release history of this particular program is much more complex than any of the others, in part because much of the original development was done in the 1990s long before I had even heard of CVS, so at the very least felt it better done as a separate endeavour.
StopwatchCE
Few people would have the hardware to run Windows Mobile 6 programs, so there was no point in keeping this online in binary-only formats. However I remember how tricky it was getting the original build environment working, and that was with a system running Windows Server 2003 — getting a working WindowsCE development environment under Windows 7 is covered in a separate article, and ironically was actually easier than expected, although this did not extend as far as trying to deploy to actual hardware.

Summary

I did not set out to move all my software projects into repositories, but once I started moving them across, my original software website was looking increasingly bare. In the end I decided to go the whole hog, moving everything onto Bitbucket, and simply doing away with my old software site. One side-effect of the whole process is seeing exactly what I had to show-case, and as it turned out was more than I expected.