Skip to content

docs: sync config.sample.php parameters for 10.15 - #142

Open
oc-tmueller wants to merge 1 commit into
mainfrom
docs/sync-config-sample-10.15
Open

oc-tmueller wants to merge 1 commit into
mainfrom
docs/sync-config-sample-10.15

Conversation

@oc-tmueller

Copy link
Copy Markdown
Contributor

Same staleness #138 just fixed for 10.16, on the 10.15 line. web-updater.enabled was added to core's config/config.sample.php in owncloud/core#41385 — present on the 10.15 branch too — and this page was never regenerated.

Regenerated with config-to-docs from core 10.15, not hand-written. The added block is byte-identical to the one #138 added for 10.16, which is expected: config.sample.php is itself identical between origin/10.15 and origin/10.16, and after this the two published pages are byte-identical too.

Why this completes something

With this merged, all three published server versions regenerate to an empty diff against their core branch:

docs core branch keys drift
content/server/11.0 master 159/159 none
content/server/10.16 10.16 159/159 none (after #138)
content/server/10.15 10.15 159/159 none (this PR)

Verified by regenerating all four generated pages and diffing, and separately by comparing core's full top-level key set against each page's sections — no key missing, none extra, order identical. 11.0 correctly lacks web-updater.enabled: the whole updater/ directory is gone on master.

That empty-diff state is the precondition for checking it in CI rather than discovering drift years later, which is the follow-up.

Two core-side issues this surfaced, neither fixed here

Both are in core's comment text, so fixing them in generated output would re-break the invariant above.

1. A contradiction, as flagged on #138. A few lines above the insertion point, upgrade.disable-web still says "The web based updater is enabled by default" — invalidated by the very commit that added the parameter being synced here.

2. Published documentation is currently losing information. Core writes:

 * 0 -> Never check the filesystem for outside changes, provides a performance
 * 1 -> Check each file or folder at least once per request

and all three published pages render:

-> Never check the filesystem for outside changes, provides a performance

The 0 and 1 are gone, so a reader cannot tell which value does which. Cause: the converter strips a line's leading run when it is a single character followed by - — a filter that exists to pull indented - lists flush left. It is now documented in config-to-docs#31, and this is a live instance of it. Fix is a one-line rewording in core (e.g. backtick the values, or use 0: instead of 0 ->).

Checks

npm ci && npm run antora && npm test pass (51 tests); the new section renders on the built 10.15 page. Region above the // header end marker byte-identical to main.

🤖 Generated with Claude Code

The same staleness just fixed for 10.16 in #138: core added
'web-updater.enabled' to config/config.sample.php in owncloud/core#41385,
which is present on the 10.15 branch too, and the generated page was never
regenerated.

Regenerated with config-to-docs from core's 10.15 branch. The diff is the one
missing section, byte-identical to the block #138 added for 10.16, and the
hand-written header above the "header end" marker is untouched.

With this, all three published server versions regenerate to an empty diff
against their core branch, which is the precondition for checking that
automatically rather than discovering drift years later.

The same caveat as #138 applies: the pre-existing 'upgrade.disable-web'
comment a few lines above still claims the web updater is enabled by default,
which owncloud/core#41385 invalidated. That wants fixing in core, not here.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: Thomas Müller <323649642+oc-tmueller@users.noreply.github.com>
@oc-tmueller
oc-tmueller requested a review from a team as a code owner September 21, 2026 15:11
oc-tmueller added a commit that referenced this pull request Sep 21, 2026
The two config parameter pages per server version are generated by
config-to-docs from core's config/config.sample.php and
config.apps.sample.php. Everything below the "header end do not delete or edit
this line" marker is machine output. Nothing enforced that, so a hand edit
there looked correct, rendered correctly, passed CI, and would have been
destroyed the next time anyone regenerated - and drift in the other direction
went unnoticed for two releases, which is what #138 and #142 just repaired.

This regenerates every version from its core branch and fails on any
difference, so the pages are provably generator output.

Nothing here infers success from an exit status, because convert.php exits 0 on
both of its own failure paths - unreadable input and unwritable output. Every
file is checked before use and the pages actually regenerated are counted and
asserted. Without that, a sample renamed in core would leave the pages
untouched, the comparison would find nothing, and the job would pass having
checked nothing at all - which is precisely the failure this workflow exists to
catch, one level up.

The comparison snapshots each page before regenerating and then plain-diffs the
two, rather than asking git. The pages are just files, and git inside this
container cannot see the workspace repository even though actions/checkout
populated it with git - which is worth knowing, but not worth depending on.

Other choices worth stating:

The loop is driven by the content/server/* directories themselves rather than a
version list, so a new server version cannot be added and silently left
unchecked. The core branch is resolved by name, falling back to master only for
the version still in development - and that fallback is verified against
master's own OC_VersionString, so a directory that matches no core branch fails
loudly instead of being regenerated from the wrong source.

git ls-remote's "no such branch" (exit 2) is distinguished from every other
failure. Conflating them would let a transient network error resolve 10.16 to
master and then fail the comparison for a baffling reason.

It is deliberately not path-filtered: a required check that is skipped reports
as perpetually pending and blocks merges, the trap already documented at length
in lint-pr-title.yml. The cost is that drift caused by a core commit surfaces
on an unrelated author's PR, so there is also a nightly run to find it first.

PHP comes from owncloudci/php:7.4 as a job container rather than a third-party
setup action, per the Actions policy in AGENTS.md. Inside a container the
default shell is sh, so bash is requested explicitly. The converter is
installed with `composer install`, not `update`: its comment parsing lives in
phpdocumentor/reflection-docblock, accepted as ^4.3.0 but pinned in the lock,
and floating it can change the generated output. The converter checkout itself
is deliberately unpinned - the question being asked is whether the pages match
what a maintainer running ctd.sh today would produce.

On failure the explanation and the full diff go to the job summary, and the
regenerated pages are uploaded as an artifact, so the fix can be downloaded
rather than copy-pasted out of a log.

Verified by running the job's own script in that container against four cases:
an in-sync tree passes and reports 6 pages across 3 versions; a hand edit below
the marker fails with the diff; an edit above the marker still passes, because
the generator preserves that region by design; and a version directory with no
corresponding core branch fails naming the mismatch.

Stacked on #142 - the check only goes green once 10.15 is in sync.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: Thomas Müller <323649642+oc-tmueller@users.noreply.github.com>
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