As VaMP gets put to use on projects others than my own, by hands other than my own, feedback comes, discussions happen and, as a result, it's not that long1 until there's added functionality in the form of two new commands: summ and sigdiff.
Alongside these two new commands, there are also smaller convenience-related changes such as a more user-friendly ordering of files in the output. Note though that large as well as all smaller changes made at this time are *not* mandatory in any way, nor breaking compatibility in the slightest. This is, of course, exactly natural and proper - changes are not impositions but offers made to the users, to be weighed and adopted if and *only* if users truly consider that they are indeed worth the cost. Not mandatory "upgrades", not breaking compatibility, not forced through in any way. If you have a use for summ and sigdiff or would simply prefer the new ordering of files in the output, then you'll take the latest VaMP but otherwise you are perfectly fine and welcome to keep using whatever other version of VaMP you already have and are fine with. This said and underlined, let's dig in and see in more detail what exactly are summ and sigdiff doing in VaMP.
Summ
The aim of summ is to allow the exact reverse operation of diff. While diff takes as input two directories (or even files2) and produces as output a 'recipe' for obtaining the "newer" one from the "older" one (in whatever way new and old are defined by the user, really), the newly added summ takes as input such a 'recipe' aka a diff file alongside a directory and proceeds then to apply to this directory the steps as found in the diff file. If one applies diff to directories a and b, producing the diff file d describing the steps to get from a to b, then applying summ to d and a will result in b.
If, however, one applies summ to d and some other directory e, the result will be failure with an error message identifying the first place where e was found to be different from the input that the diff file assumes - meaning in this case, from the original a. Because unlike the more common, non-VaMP varieties of 'diff' and corresponding 'merge', the point is to know quite clearly and explicitly the full state of the directory in question at all times, not just the bits and parts that are touched by one step or another.
As a user, I really do care about the input directory as a whole or otherwise I'd simply discard the part I don't care about and make the load lighter to start with. Consequently, I'd much rather the tool supports my full interest and helps look after the input as a whole rather than letting it up to me to figure out afterwards what happened exactly and whether the result is what it was meant to be in the first place or not quite. This being said though, the tool will certainly *attempt* to do whatever it is set to do, simply providing as much information as it can on the results of this attempt and the likely underlying causes for failure, when relevant.
In short, summ works with a diff file aka the *unsigned* list of steps to bring one directory's contents to match exactly another directory's contents. By contrast, the already existing patch command works only with a patch file aka the *signed* list of steps. Thus, while diff is quite useful in practice as a preliminary step to check a set of changes before signing them, the corresponding summ has its use case in applying a set of changes whenever the user doesn't consider signing required, such as local testing for instance. There's a cost to signing, as there is a cost to everything and depending on the context, this cost might be justifiable or not. It's entirely up to the user to decide at each use whether it's worth signing or not. VaMP simply provides now the needed commands to do the job fully in either case - via patch for signed changes, via summ for unsigned changes.
Sigdiff
The sigdiff command takes as input a diff file (hence, an unsigned list of steps) and a private key, producing as output the corresponding patch signed with the given key. This decouples quite on purpose the production of a patch file at the exact sensitive point of signing - because private keys are sensitive information, it's quite naturally the case that they are kept in more secure environments that don't necessarily fit in with code development directly.
Without sigdiff, one would need to bring together the code and the private key at least for the duration of producing a signed patch. This is less than ideal and while it can be worked around (and verifiably has been worked around by myself at the very least) it goes against the very good practice of keeping private keys in air-gapped environments. With sigdiff however, the use is much more straightforward, quite similar to any other use of private keys: the diff is produced in the usual work environment where the code is but the key isn't present; then, sigdiff is applied to the diff separately, in the more secure environment where the key is but the code isn't present; finally, the resulting patch is published or otherwise used in any environment, as desired.
As a final note, there are at the moment a couple of potential further additions that didn't quite make the threshold of current usefulness to be included. So they are noted and fleshed out in VaMP's design document, ready to be implemented but not actually implemented until there is a clear need for them. Should there be any further requests or questions, they are always welcome, as usual, in the comments below for everyone and through more direct channels for those more closely involved.
In fairness and for complete history, there's the VaMP category on this blog to get the full timeline of additions to date:
- VaMP was ready to go on the 23rd August 2021
- more details of its workings were published on the 5th of September
- a discussion of what are valid files and directories for VaMP was published on the 19th of April 2022
- about 8 months later, on the 5th of May 2022 and then on the 12th of May 2022, there was the addition of a tidier alternative visualisation of patches and their dependencies, followed by the addition of html formatting and output production, bridging directly code and VaMP output to the blog
- almost one full year later, on the 4th of May 2023, the versioning and software editions capabilities were fully in place.
In between these, there was certainly a lot of use and practical experience that turned out extremely pleasant for the most part. While the pace of changes and additions might seem perhaps 'slow' from some perspectives, I think it's neither slow nor fast but just exactly right - as use informs and requires, without pressure nor ill-considered or rushed changes, allowing time to get used to things and knowing at all points that the experience thus gained is never lost but an asset that keeps increasing in value as it builds up. ↩
This is the corner bit where summ is currently *not* quite the full reverse of diff - it works on a directory, only. The case of diff applied on two files as opposed to two directories is in itself quite an odd and awkward special case from the point of view of VaMP when considering that a single file can't have attached a manifest with its history, for instance, thus little to speak of. For users' convenience and mostly in keeping with the original generic diff that did and does apply indeed to files as well as directories, VaMP's diff does the same, producing the list of changes all the same. Nevertheless, I don't really see much point in dragging along this odd special case for anything other than the diff command as such - if it's absolutely imperative for you to diff and summ a single file, simply put it in a directory and apply VaMP to that, it's not much trouble and it can even be automated via a basic script if desired, not that I can fathom such use case at all currently. ↩
Comments feed: RSS 2.0