I currently have 120 Vim plugins published on vim.org, and done 671 individual releases over a time period of 18 years. Initially, that site was the sole repository and development happened over email and by using my own home-grown version control system. But as GitHub rose to fame and Vim plugin managers appeared and eventually became a built-in feature in Vim 8.0, people wanted to consume plugins from there, leaving behind the ancient Vimball packaging format and manual updates. Therefore, I converted my plugin sources to Git repositories and published them to GitHub.
To make this transition manageable and reduce the overhead, I've developed a set of tools (both inside of Vim and as shell scripts, also tied into my custom use of the Git CLI). I've seen other prolific Vim plugin developers do similar things, even going as far as completely automating the upload of new releases to vim.org. My approach reflects my agile, incremental development style, focussing on the most tedious and error-prone steps, while still leaving some parts (especially those (web) interfaces where I have no control of and little insight into) as manual steps.
I didn't do much Vim plugin development in the past few years, but it's recently been picking up a bit again, and having the automation and checklists in place surely helped to get out of the rut and going! After releasing three (dependent-upon) plugins in a row, I realized (after completing the second one) that it might be instructional to record the terminal part of the release process.
This is how I released version 1.10 of VcsMessageRecall in three minutes:
00:00 Start: I use Git Flow as the branching model. The author now warns that the different release streams are overkill for most modern CI/CD processes, but at the time it made sense to have the opportunity of delivering hotfixes and supporting multiple code streams, and I also was very used to that model from my corporate job. I've only ever used the release flow, but that one's really smooth and I like (and advertize) the stable branch that always has the latest stable release, making it a convenient choice for casual plugin users.
00:18Update the Vim manual with the release date: I keep this a manual process because it gives me the chance for a last sanity-check before releasing it. With my setup, the only keys I need to press are j (down), W (to RELEASEME), C (change to end of line), and F8 (insert current date).
Regenerate the readme from the Vim manual: The VcsMessageRecall.txt is the Vim documentation, accessible via :help VcsMessageRecall. The GitHub project page wants a readme file. I use a custom :UpdateHelpAsReadme command that converts the help page into Markdown via a long list of :substitute commands.
00:34Verify documentation changes and commit: This is my standard Git workflow of viewing the diff and then committing the changes. The custom git release commit command just auto-generates the commit message here.
00:45Package the Vim plugin: A small shell script invokes Vim with the package manifest (a simple list of files; my own invention) and uses custom :Make and :Zip Vim commands to produce the Vimball at the default location where my browser can pick it up.
00:59Upload the Vimball to the vim.org plugin page: This means logging in (doing this manually avoids credentials handling) and navigating to the plugin page. It looks like this:
01:03Extract the changelog from the plugin manual: The upload requires the package itself, its version, and the changelog. I extract the latter from the Vim manual. I use a custom scratch buffer to lightly massage the text; closing the scratch buffer automatically puts its contents into the system clipboard, so that I can easily paste it in the web form.
01:21Vimball, new version, and changelog have been entered, and a click of the |Upload| button completes that part; doing the same on the Git side is done via $ git release finish (which is an alias for git flow release finish), which briefly opens the editor for the branch merge, version tag, and tag merge. My $ git opa alias (short for git push origin --all) concludes this part.
02:08The plugin page still needs to list new commands and updated dependencies; like the readme on GitHub, the vim.org plugin page also shows the description and plugin installation instructions. A :UpdateHelpAsText command splits the plugin manual into two parts and also transforms each. I keep the previous copies of those as private files in my working copy, :dts is a Vim alias for my :DiffToSaved that lets me check what changed (and whether I actually need to copy-and-paste this).
02:35On the plugin page, edit details; again, keeping this part semi-manual allows me to do a sanity check and avoids uploading garbage if any step of the automation breaks.
02:51Repeat with the install details; the system clipboard functions as the lightweight integration here.
03:00Done!
summary
Open source work is an unpaid hobby, so it needs to be fun and easy. I use it as an opportunity to learn new things and to improve my tooling, which then often also improves my efficiency at work. It's not as directed as coding katas (where you repeat the same exercises to get better at them), but it's practice with a purpose. Often, one achievement leads to another; in this case, the need to add more comments to the asciinema recording (which was tedious without syntax highlighting and manual editing) prompted me to write a Vim filetype for asciinema, which didn't exist so far. Another win for the Vim community!
