Rule editing workflow

[jonathonherbert]

At the moment, our workflow for publishing rules looks a bit like:

flowchart TD
rule[Rules]
publish{Publish}
edit{Edit}

rule --reads from--> edit
edit --writes to --> rule
rule --reads active rules-->
publish --publish artefact-->rule_artefact

Loading

There are problems with this workflow:

• a user can't edit an active rule without their changes hitting PROD typerighter. This matters because when we're revising rules, possibly in response to user feedback or telemetry that indicates something is wrong, we expect users to test the revised rule before publishing it. We want to avoid this testing phase being exposed to PROD users.
• there's no way to 'republish' a version of a rule. This matters because we think recording revisions of rules matters, and we don't necessarily want to record every possible revision. A model similar to restorer is preferable, where we record new versions when it's appropriate – in the case of Typerighter, I think that'd be every time a rule is published, or republished.

Introducing a 'fork-to-live' model, similar to the one we use for draft and live content in flexible-content, is one way to solve this. The workflow could look something like:

flowchart LR
rule_draft[Draft rules]
rule_live[Live rules]
rule_history[Rule history]
rule_artefact["Rule artefact (used by checker)"]
publish{Publish}
edit{Edit}

subgraph "Users edit a rule in its draft state" 
rule_draft --reads from--> edit
edit --writes to --> rule_draft
end

subgraph "Publishing produces an artefact and saves the old revision in the rule history"
rule_draft --reads from--> publish
publish --writes current draft rule to-->rule_live
publish --writes current draft rule, with reason for revision, to-->rule_history
publish --publishes live rules to-->rule_artefact
end

Loading

What do we think?

[aracho1]

This looks good to me, with one question. With regards to when we're revising rules,...we expect users to test the revised rule before publishing it., are we thinking of some kind of config / feature switch that lets users test on Composer with 'draft' rules? Or simply a placeholder while users manually test on their end?

[jonathonherbert]

I think there are a few possible stories, including:

• as a user, I can add snippets of text with parts that I expect to match, and snippets that I don't expect to produce match. The tool will tell me when these tests pass or fail, and will not allow me to publish a rule with a failing test.
• as a user, I can run my rule against lots of Guardian copy (say, for example, the 100 most recently published articles), and surface the matches that this rule creates. I can quickly review the matches to get a rough idea of whether the rule is performing as expected.

Do those stories make sense in the context of your question? There may be others we can imagine – our stories doc (which should probably be in VCS!) has a few under 'testing rules'.

[aracho1]

These would be fantastic features to have!

[rhystmills]

This looks good to me.

If there's one shared 'draft' version between all users (which seems reasonable, especially given how few users there are) - do we need something like presence-indicators to indicate that someone else is currently editing the rule?

This would add a bit of complexity, and the pay-off is smaller when there are fewer users.

[jonathonherbert]

Definitely possible! I think we can guard against rules being edited by checking revisionId, as we do in Composer. We could implement that, and then wait until we record a few conflicts in PROD, to decide whether it's worth building?

[Fweddi]

Looks great.

The proposed workflow suggest we save the 'previous live rule' to the history table. Is there any reason why we wouldn't want to save the 'current live rule' to the history table instead?

My reasoning is that as soon as you publish a live rule, it becomes part of history - similar to a git commit.

In the same story where a user might want to see previous revisions and revision reasons, there will likely want to see the current revision reason too - so may as well pull these both from the history table.

It's also a slightly simpler model, in that you're not having to move information around between tables.

There's a chance this is what you meant from your workflow, and I've misinterpreted things.

[jonathonherbert]

Agreed, makes perfect sense. There's a question as to whether the rule history and the list of live rules are separate tables, or stored in the same place with a flag to mark live rules.

It's an implementation detail that we can resolve as we work on that feature.