Algorithm diff's vs. full listings about vc-di-eddsa HOT 7 CLOSED

Resolution? I didn't realize but for the ECDSA JCS update w3c/vc-di-ecdsa#12 I did a full listing rather than a diff. If folk desired I do a PR to resolve this issue with a full listing.

from vc-di-eddsa.

Resolution? I didn't realize but for the ECDSA JCS update w3c/vc-di-ecdsa#12 I did a full listing rather than a diff. If folk desired I do a PR to resolve this issue with a full listing.

The issue is with repetition and introducing bugs in the algorithm via repetition. We can do a full listing, as an act of last resort, but I'd rather try to figure out a way that we can template these algorithms and replace parameters/steps in them (and re-use the algorithm templates everywhere). That we're having to do this is demonstrating that we don't quite have things abstracted in the right ways across all of the specifications.

from vc-di-eddsa.

I thought the concern was more readability. The algorithms and their abstractions seem reasonable to me. Was just trying to see if there was a straightforward way to close this issue.

Cheers Greg

from vc-di-eddsa.

We could conceivably do one full listing, with a bunch of conditionals to handle the branch points, to which we point all the specs. This would not include the full, blended listing nor a minimized, spec-specific listing in each spec, increasing inconvenience for the reader, but it would prevent the potential inaccuracy of multiple, slightly-different full-listings.

from vc-di-eddsa.

We could conceivably do one full listing, with a bunch of conditionals to handle the branch points, to which we point all the specs.

I believe we already do this today, @TallTed. Here's an example of the base algorithm which adds a proof:

https://w3c.github.io/vc-data-integrity/#add-proof

and the specialization of that base algorithm in one of the cryptosuite specs:

https://w3c.github.io/vc-di-eddsa/#add-proof-eddsa-2022

The only thing that I can think to do differently in that case, is to make the base algorithm a function that generates text, where if you give it fragment identifiers in a document, it'll point to those specific sections in the algorithm. Doing this will inevitably lead to people complaining that they now have to modify code if they want to change the base algorithms (which might be a cost worth paying). Doing this wouldn't allow arbitrary addition/removal of steps from the base algorithm, but if one needs to do that, that's a good indication of an extension point that's needed in the algorithm.

The other bits that folks, including myself, don't seem to like are the diff'ing of established algorithms, like this one:

https://w3c.github.io/vc-di-eddsa/#jcs-eddsa-2022

... where we effectively say: "Do what algorithm X is doing, except for in steps Y and Z, do this other thing instead." It feels like it works fairly well for jcs-eddsa-2022 (or, at least, it's implementable by reading it -- though it's not entirely easy for implementers to piece everything together).

This would not include the full, blended listing nor a minimized, spec-specific listing in each spec, increasing inconvenience for the reader, but it would prevent the potential inaccuracy of multiple, slightly-different full-listings.

Yes, exactly, which is why the specs are written in the way that they are right now.

In what way do you feel we should improve on this, @TallTed? (and are those improvements purely editorial -- I expect they are).

from vc-di-eddsa.

This is what we're doing now — "Do what algorithm X in document Q is doing, except for in steps Y and Z, do this other thing instead." — which requires the implementer to get document Q in addition to whatever doc they're working from right now, and to accurately and completely apply those step changes.

I submit that such developer is more likely to make an error when working with multiple specs but only to the cross-spec algorithm than we are if we try to keep these algorithms up-to-date across all such specs, especially if we put relevant comments into the source HTML such that we can see that if we edit the algorithm in document Q we should apply similar/identical changes to the algorithm in documents R, S, T, U, and V — with such reflective comments in each of those documents.

Yes, this is more work for us, but it is the most likely to deliver success across the board.

Second most likely to deliver success across the board (which I tried to describe above, but don't think it came across) would be to use one external document for each algorithm, with the fully written steps laid out like a "choose your own adventure", with branches wherever one or more specs differ from the other(s). This would also be a fair amount of work for us, especially on the first iteration, and it still leaves open a lot of potential error points for the developers working from this document, just making those a bit less likely to bite because of the whole algorithm being in one document, no matter which spec they're working from.

At best third most likely to deliver success across the board is what we have now, with the fully detailed algorithm steps in one document, and "change these steps" instructions in the documents where the algorithm differs. I think this is begging for trouble, and at minimum we should include notes of "these perils await you if you don't apply the algorithm diff correctly, and hence don't execute the algorithm correctly" to at least encourage double- and triple-checking of their application of the diff. I expect that this option will result in plenty of developer error, leading to the perils just mentioned.

from vc-di-eddsa.