Skip to content

feat(flow): give a flow's rationale a column, so the database stops eating it - #2439

Merged
rubenvdlinde merged 3 commits into
developmentfrom
feat/flow-comment-field
Aug 12, 2026
Merged

rubenvdlinde merged 3 commits into
developmentfrom
feat/flow-comment-field

Conversation

@rubenvdlinde

Copy link
Copy Markdown
Contributor

What

Adds a comment column to openregister_flows so a flow's authored rationale survives a database round-trip, plus two pre-existing fixes found on the way.

Implements decision 3 recorded on #529.

Why

A flow authored as a definition file carries its reasoning in a top-level $comment. On hydra's lock reaper that is 90 lines recording four defects and what prevents each recurring. The table had no column for it, so importing such a file and regenerating it from the database returned a flow without that text — silently, because a flow with no rationale looks exactly like one whose author wrote none.

The standing workaround was to regenerate by merging file and database rather than exporting. That kept the text alive but made the file its only home: a flow edited through the UI could not carry a rationale at all.

comment is distinct from the two fields beside it — description is the one-line label the UI lists a flow by, notes is a working scratchpad.

Commits

feat(flow) the column, entity field, service mapping, migration, 6 tests
fix(tests) four Flow tests never require the helper trait they use — the whole 16,303-test unit suite was unrunnable locally
style the two pre-existing phpcs errors on development

The test-loading fix

composer test:unit fatals on an untouched development outside a Nextcloud checkout:

Fatal error: Trait "…\FiltersFlowLevelFindings" not found
in tests/Unit/Service/Flow/FlowNodeConfigDialectTest.php on line 61

PHPUnit aborts the entire run at the first fatal, so no unit test could be run locally, and the 51 tests in those four files never ran anywhere the server autoloader was absent. In CI the trait resolves only because tests/bootstrap.php requires the server's tests/autoload.php when it finds a Nextcloud root.

Fixed with an explicit require_once per consumer — the convention the AppHost and Mcp fixtures in this repo already follow. Two alternatives were tried and rejected:

  • autoload-dev PSR-4 — 572 test classes use namespaces that do not correspond to their paths; composer prints a skip warning for each.
  • classmap over tests/ — would make tests/stubs/'s OCP stubs autoloadable, which has bricked an instance here before.

Verification

  • PHPUnit 16,303 tests, 0 failures, 0 errors (PHP 8.4). Before this branch the suite could not complete at all outside a NC checkout.
  • phpcs clean — confirmed covering all 1,428 files in lib/ (-v | grep -c '^Processing '); the "72/72" the progress line prints is a parallel=75 batch counter, not a file count.
  • PHPStan [OK] No errors.
  • PHPMD 32 findings before, the same 32 after — diffed against the pristine files mounted over the working tree, with only a line-number shift on one pre-existing finding. Those 32 are pre-existing on development and untouched here.

Positive controls

Removing the field mapping turns four of the six new tests red. The fifth — a partial update must not blank a stored comment — is deliberately driven through the update path: on a create the field starts null, so the same assertion there would hold no matter what the code did. Its counterpart pins that an explicit null still clears the field.

…quire

`composer test:unit` FATALS outside a Nextcloud checkout:

    Fatal error: Trait "…\FiltersFlowLevelFindings" not found
    in tests/Unit/Service/Flow/FlowNodeConfigDialectTest.php on line 61

Not a new break — it reproduces on an untouched `development`. The suite
matches `*Test.php`, so a helper that is not itself a test case is never
included, and composer declares no `autoload-dev`, so nothing autoloads the
test namespace either. In CI the trait resolves only because `tests/bootstrap.php`
requires the SERVER's `tests/autoload.php` when it can find a Nextcloud root.

The cost was not the four files: PHPUnit aborts the whole run at the first
fatal, so the ENTIRE 16,303-test unit suite was unrunnable locally, and the
51 tests in these four files never ran anywhere the server autoloader was
absent.

Fixed the way the AppHost and Mcp fixtures in this repo already do it — an
explicit `require_once` in each consumer. An `autoload-dev` PSR-4 rule was
tried first and rejected twice over: 572 test classes use namespaces that do
not correspond to their paths (composer prints a skip warning for each), and
a `classmap` over `tests/` would make `tests/stubs/`'s OCP stubs autoloadable,
which has bricked an instance here before.

Verified: 16,303 tests, 0 failures, 0 errors.
`lib/AppInfo/Application.php` indented a quoted error message three spaces
inside a `//` comment run; `ObjectWriteNode.php` had a 166-character
translatable string on one line.

The long line is wrapped as concatenated literals inside `t()` — the form
already used elsewhere in the same file (line ~1264), so the extractor still
sees a literal. Assigning the message to a variable first would have hidden
it from translation extraction entirely.
…ating it

A flow authored as a definition file carries its reasoning in a top-level
`$comment`. On hydra's lock reaper that is 90 lines recording four defects and
what prevents each recurring. `openregister_flows` had no column for it, so
importing such a file and regenerating it FROM the database returned a flow
without that text — silently, because a flow with no rationale looks exactly
like one whose author wrote none.

The standing workaround was to regenerate by MERGING file and database rather
than exporting. That kept the text alive but made the FILE its only home: a
flow edited through the UI could not carry a rationale at all, and two authors
working on the same flow by different routes disagreed about why it was shaped
that way with nothing to reconcile them.

- `comment` TEXT on `openregister_flows`, nullable. TEXT because the existing
  bodies already exceed 6,000 characters and a length-capped column would
  truncate on write rather than refuse it.
- `Flow::$comment`, in `addType()` and in `jsonSerialize()`.
- `FlowService::applyEditableFields()` accepts `comment`, and normalises the
  `$comment` a definition file actually uses — that key cannot be a column
  name, so it is translated once here rather than at every call site. An
  explicit `comment` wins over the alias: a UI edit is a deliberate write,
  `$comment` is whatever the file happened to carry.

Distinct from the two fields it sits next to: `description` is the one-line
label the UI lists a flow by, `notes` is a working scratchpad.

Six tests, positive-controlled: removing the field mapping turns four of them
red, and the fifth (a partial update must not blank a stored comment) is
deliberately driven through the UPDATE path — on a create the field starts
null, so the same assertion there would hold no matter what the code did. Its
counterpart pins that an explicit null still clears the field.

Closes the decision recorded on #529.
@github-actions

Copy link
Copy Markdown
Contributor

Quality Report — ConductionNL/openregister @ 832ef72

Check PHP Vue Security License Tests
lint ✅
phpcs ✅
phpmd ❌
psalm ✅
phpstan ✅
phpmetrics ✅
eslint ✅
stylelint ✅
build ✅
check-specs ✅
test-l10n ✅
composer ✅ ✅ 173/173
npm ✅ ✅ 546/546
PHPUnit ❌
Newman ✅
Playwright ✅
Hydra gates ❌

Quality workflow — 2026-08-12 07:57 UTC

Download the full PDF report from the workflow artifacts.

@rubenvdlinde
rubenvdlinde merged commit 61c9f38 into development Aug 12, 2026
23 of 29 checks passed
@rubenvdlinde
rubenvdlinde deleted the feat/flow-comment-field branch August 12, 2026 08:37
@rubenvdlinde
rubenvdlinde restored the feat/flow-comment-field branch August 14, 2026 08:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant