Fossil Forum

RFC: "reason for edit" comment (C-card) in forum posts
Login

RFC: "reason for edit" comment (C-card) in forum posts

RFC: "reason for edit" comment (C-card) in forum posts

(1) By Stephan Beal (stephan) on 2022-05-20 07:19:12 [link] [source]

Forum artifacts in fossil do not currently support a C-card (change comment). "What if" we added that for in supporting a "reason for edit" field?

The use case: in this forum and sqlite's, on rare occasion i'll edit a post made by a newcomer to add (most commonly) triple-backticks around a large block of SQL or console output or similar which they've pasted in. (Newcomers often don't know how to do that.) In such edits i'll add a note to the bottom explaining the edit because the forum will show the post as edited, which seems likely to confuse or bother folks if they don't know the reason it was edit.

Supporting a C-card in forum posts would give us a place to explain such edits non-intrusively and allow us more freedom in where/how to show the "why it was edited" comment in the forum UI.

Technically speaking, adding support for the C-card is absolutely trivial. In practical terms, though, when adding support for a new card type in an artifact (like the C-card in wikis, added a couple of years ago), we cannot immediately start using that support because such artifacts will not parse as artifacts on any older fossil version. That is only to say that this is easy to do but less easy to actually deploy: we'd likely have to wait a couple of years before we start using the feature, in the hope that most clients have been updated by that point. Clients which are older would simply "not see" such posts as forum posts. They'd be in the blob table but would not show up as posts because they don't strictly conform to the artifact format supported by older clients.

Opinions?

(2) By graham on 2022-05-20 08:00:35 in reply to 1 [link] [source]

A "meta" opinion...

I'm only peripherally aware of the use of card-types in Fossil, so I could have the wrong end of more than one stick, but my reading of the problem when considering this sort of addition is that older clients are "very strict" about what card-types can be attached to an artifact: when they were written, C-cards didn't exist (or weren't allowed), so the artifact as a whole is ignored (as opposed to ignoring just the unknown card-type).

There may be very good reasons for not doing so (and I admit I've not gone looking for one), but is there an argument for making artifact/card parsing more tolerant? If they see a card-type they don't know about, they ignore it as if it wasn't there (similar to how unknown tag-types are handled by TIFF-file readers).

Of course, you'd have to wait "a couple of years" for (most) clients to get updated before you could leverage such a change, but once that's done, you shouldn't have to wait two years each time a new card-type is added before you could start using that card-type.

(3) By Stephan Beal (stephan) on 2022-05-20 08:50:33 in reply to 2 [link] [source]

but my reading of the problem when considering this sort of addition is that older clients are "very strict" ... so the artifact as a whole is ignored (as opposed to ignoring just the unknown card-type).

That's correct. If it fails in that way, fossil considers that blob to be "just a blob" and not an "artifact."

There may be very good reasons for not doing so (and I admit I've not gone looking for one), but is there an argument for making artifact/card parsing more tolerant?

That Way Lies Madness. In the 90s and early 2000s there was a trend in software to "be lax in what you accept and strict in what you output," but that methodology proved to be truly problematic long-term (and it's at least partly to blame for PHP and MySQL being the atrocities they are (noting that that's my personal opinion and not an Official Stance of this project!)).

Fossil's only way to distinguish artifacts from non-artifacts is whether or not the blob can be parsed like an artifact. If it can, it's an artifact. If it can't, it's not. There is no wiggle room for "it almost can." If fossil had a way of recording (in the persistent SCM history) "this blob is an artifact and this one is opaque," then "partial success" would be an option, but it doesn't record that, opting instead for the approach of "if it quacks like a duck, it's a duck, but a goose's quack is distinctly different from a duck's quack."

Of course, you'd have to wait "a couple of years" for (most) clients to get updated before you could leverage such a change, but once that's done, you shouldn't have to wait two years each time a new card-type is added before you could start using that card-type.

That's very true, but card changes are intended to be extremely rare and there is a technical upper limit on which changes can be made (e.g. all combinations of valid card types in an artifact must unambiguously identify the type of that artifact, so we cannot have two artifact types which allow the same combinations of card types). Ticket edits, on the other hand, are collections of free-form property/key pairs, and are well-suited to this type evolution. That same freedom, however, means that any collection of key/value pairs is conceptually a valid ticket change, whereas we definitely do not want to recognize a random non-artifact as an artifact simply because it almost looks like an artifact. That Way Lies Madness.

(4) By Brian Tiffin (btiffin) on 2022-05-20 15:25:20 in reply to 1 [link] [source]

With no real grasp of the size of the ripple effect, I'd not be against adding C-card meta data to posts.

As an alternative, on the forums I manage, I'll often do a fix up, especially to remove reply-to added by repies via an email systems (Forum's don't need to carry around the redundant context), I'll also add a line at the bottom:

mod edit to ...

As an alternative, if that might be a less ripply "change".

Have good

(5) By george on 2022-05-21 03:26:42 in reply to 1 [link] [source]

I use the forum moderation feature mostly just by reading posts that were kindly moderated by others ;-)
So any way to relief the strain from the moderators seems reasonable to me.

I don't object to C-cards in forum posts' artifacts. If I understand correctly, that may not be strictly necessary though: an alternative would be to use a control artifact with a well defined tag name. In that case older versions of Fossil would still recognize the posts (and ignore the comments in the corresponding control artifacts).

The value of this special tag need not be a comment itself. Please consider the following idea:
A repository may have

  1. a separate document ("the rules") that elaborates requirements and recommendations for forum posts (and that is accessible to forum users);

  2. a mainmenu-like setting that defines a list of reasons with the links to the corresponding sections of that document;

When the post is edited the reason may be specified just by selection of the appropriate item from the list. When the post is rendered a reason is rendered in the form of a hyperlink to the corresponding section of the rules.

Apart from all the above I think that the ability to see the actual diff between the versions of a post would be really useful for all users of a forum.

(6) By Stephan Beal (stephan) on 2022-05-21 10:04:19 in reply to 5 [link] [source]

an alternative would be to use a control artifact with a well defined tag name.

That is definitely a viable alternative. It's far more code because it separates the forum post from the comment/reason but is backwards compatible and potentially more flexible ("search for posts edited for reason X"). That would certainly be worth prototyping.

Apart from all the above I think that the ability to see the actual diff between the versions of a post would be really useful for all users of a forum.

IRC the diff view is not implemented but it's possible to see all versions. A diff view is problematic in forum posts because each paragraph is a single line in the diff, making the diff difficult to read. i'm currently on a tablet so won't search for an example.

(7) By george on 2022-05-21 17:07:50 in reply to 6 [source]

... alternative. It's far more code ...

True. I dunno whether it is worth going that route.

A diff view is problematic in forum posts because each paragraph is a single line in the diff, making the diff difficult to read.

I think that this problem can be tackled from two sides:

  1. Incentivize writers to keep the length of lines in bounds by manually inserting line breaks.
    I mean some smart composition and/or styling of the text input area in Fossil's WebUI. I would appreciate some hints on how that could be done.

  2. Use a specialized mode of the diff algorithm where long lines are displayed in such a way that matching sub-strings are aligned.
    There could be an option that instructs Fossil when this mode should be used (e.g. just within forum posts and for lines that are longer than 120 characters).

The implementation of the above seems quite nontrivial. I'm curious if someone else is interested in that feature.

(8) By Stephan Beal (stephan) on 2022-05-21 20:07:04 in reply to 7 [link] [source]

... alternative. It's far more code ...

True. I dunno whether it is worth going that route.

i don't yet know if it's worth it, but it is not a bad idea at all and may have other uses. e.g. i'd very much like to eventually implement (or see implemented) tagging of posts so that we can do search by tags. All of the required infrastructure was put in place for that in the past year, e.g. tag propagation works on forum posts, we just need UI features for manipulating the tags and support in the search bits to support searching by hashtags. We have a branch which can parse hashtags from markdown docs but it's currently unused because we don't have a great (working) use case for it.

(So if anyone's looking for features to hack, there are some ideas!)

I think that this problem can be tackled from two sides:

In practice i don't think it would be a "real" problem because the types of edits which are normally made by admins are wrapping chunks of "code" in trip-backtips or adding markup to a URL to hyperlink it. In the abstract, though, diffs of forum posts and wiki pages have usability issues because of their long lines.

There could be an option that instructs Fossil when this mode should be used (e.g. just within forum posts and for lines that are longer than 120 characters).

We actually have the same problem in the wiki - those diffs suffer from the long-line thing. A variant which could align those differently sounds interesting, but...

The implementation of the above seems quite nontrivial.

Exactly :).

I'm curious if someone else is interested in that feature.

And if they're interested in coding it! :)