Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
docs: add unstable qualification branch to promotion policy #513
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Uh oh!
There was an error while loading. Please reload this page.
docs: add unstable qualification branch to promotion policy #513
Changes from all commits
60a94b5088ccd1File filter
Filter by extension
Conversations
Uh oh!
There was an error while loading. Please reload this page.
Jump to
Uh oh!
There was an error while loading. Please reload this page.
There are no files selected for viewing
No visible changes here.
But you can view the diff anyway.
CI and diagnostic artifacts
Pull requests to
devorunstablerun the Linuxagent-fast / buildworkflow. Merges intounstablerequire that check. Topic PRs intodevstill run the workflow for signal, butdevno longer carries branch-rule status requirements. The workflow classifies the diff, runs source and contract checks, compiles affected targets, and runs focused tests. Pull requests require one structured changelog fragment underchanges/named after the head branch. Subsequent integration-branch pushes skip that PR-only check so a merged topic fragment is not rejected for not beingchanges/dev.md. Stacked topic branches may carry their parent fragments, but every added fragment is validated. Format and clang-tidy run on added, modified, renamed, or copied C/C++ files only; deleted paths still classify modules. These are the fast checks for the shared integration baseline. The full Linux and Windows build-and-test jobs run for release qualification. These are the two platforms Loop V1 supports; macOS CI is a post-V1 track under MIC-336 / docs/PLATFORM_SUPPORT.md. Packaging artifacts are produced only forstablepushes and manual workflow runs.The standalone
Documentation truthworkflow runs for the policy branchesdev,unstable, andstablepull requests and pushes. It checks every ADR's verification header and fails whendocs/generated/architecture-catalog.jsonis stale. Product versioning is SemVer 2.0 (0.2.0-alpha); CI also runsscripts/ci/check_version_policy.py.The
release_okjob in.github/workflows/release-gate.ymlis the single GitHub Actions status required by the protectedstablebranch. It always runs and fails when any required dependency failed, was cancelled, was skipped, or did not report. Requiring the platform-specific jobs directly would create multiple checks for the same gate. The release-gate workflow runs for every pull request targetingstableand formerge_groupevents; it has no path filters.unstablerequiresagent-fast / buildfor merging;stablerequiresrelease_ok.Hosted fuzzing (
.github/workflows/fuzz.yml) validates the manifested regression corpus underFuzz/corpus/and runs each harness's owned seeds with-runs=0before time-bounded mutation.When a Windows test run fails, GitHub Actions uploads its CTest logs as the
windows-test-logsartifact. Store any intentional, long-lived diagnostic artifact in the related issue or release attachment; do not add local build or test output to the repository.Generated dependency state
The dependency source of truth remains
vcpkg.json,vcpkg-configuration.json, and the reviewed overlay ports. Install trees, downloaded packages, and binary caches are generated state and must not be committed. CI stores its vcpkg downloads and install output in the GitHub Actions cache; local Docker/fuzz workflows may use ignored.docker-vcpkg*directories.scripts/ci/check_generated_dependency_paths.pyinspects the Git index and fails CI if any known generated dependency path is tracked again.Windows local test executables
Windows test executables need the configured Qt and Loop/vcpkg runtime DLLs beside the executable. If the dependency set is not deployed into the build output, the process can wait behind a missing-DLL system error instead of printing a normal test failure. For a Release test directory, run
windeployqtwith the configured Qt root and deploy the Qt/Loop dependencies into that same directory before invoking CTest. Generated DLLs and plugin directories remain local build output and must not be committed.Tracked source integrity
scripts/ci/check_source_integrity.pyruns before Qt/vcpkg configure on everyci.yml,release-gate.yml, andfuzz.ymlinvocation. It inspects the Git index (git ls-files) and fails when tracked content includes:build/,build-*),.docker-vcpkg, orCMakeCache.txtdebug-*.logfiles or one-offscripts/debug-*scriptsgit diff --checkover the full treeNegative fixtures live in
scripts/ci/test_check_source_integrity.py.Updating pinned workflow dependencies
Workflow actions, vcpkg, and binary packaging tools are pinned to exact revisions or SHA-256 checksums. The source of truth for packaging tools is
.github/pins/packaging-tools.json(see its README); the vcpkg baseline is thedefault-registry.baselineinvcpkg-configuration.json. Workflows derive their vcpkg checkout and all tool digests from those files at runtime, and theVerify supply-chain pinsstep (scripts/ci/check_supply_chain_pins.py) fails the build if any action is not a full commit SHA, any package URL is mutable (continuous/latest), or a pin is missing.To refresh a pin:
.github/pins/packaging-tools.json(for packaging tools) or the workflow's copy of a full action SHA.Do not replace a pin with a moving tag such as
main,latest, orcontinuous. DigiCert KeyLocker (MSIsigning) must additionally be added todigicertKeylockerinpackaging-tools.jsonbeforeSIGN_MSIcan proceed; the signing step refuses to run against an unpinned toolchain.Sentry debug files
Windows Release builds with
LOOP_ENABLE_SENTRYemit PDBs (/Zi+/DEBUG:FULL) so crashpad minidumps can be symbolicated. After the Windows CI and MSI packaging jobs,scripts/ci/upload_sentry_debug_files.ps1uploads Loop PDBs toberry-studios/loop-pdfon the EU region (https://de.sentry.io) using the pinnedsentryClibinary. GitHub Actions cannot referencesecretsinif:conditionals, so the workflow always runs the step;upload_sentry_debug_files.ps1no-ops whenSENTRY_AUTH_TOKENis unset (fork pull requests). PDBs are not installed into the MSI; they stay on the Sentry debug-file store. Store the token as the repository secretSENTRY_AUTH_TOKEN(project:releasesor broader); do not commit it.Repo map
Loop repository layout, fork relationship, branch policy, and upstream tracking policy.
Repositories
stable(default/release),unstable(qualification),dev(integration)master(upstream only)Loop owns the product decisions, branding, release policy, and downstream changes. PDF4QT remains the upstream source for the PDF engine and inherited tooling. Do not infer Loop branch policy from upstream's
masterbranch.Branch policy
devis the first integration branch.unstableis the qualification branch; it carries the fast integration gate formerly required ondev.stableis the release branch and repository default.dev, stay focused, and merge back todev.dev→unstable→stable.masteris not an active Loop branch.The reviewed machine-readable policy is
branch-policy.json. The current factual branch and workflow audit is tracked in GitHub issue #232.Versioning
Loop uses Semantic Versioning 2.0. The current product version is 0.2.0-alpha. Policy:
version-policy.jsonandVERSIONING.md. Former0.0.3–0.0.60.0.3ΓÇô0.0.6 gates are0.1.1–0.1.40.1.1ΓÇô0.1.4.Upstream tracking policy
Parser, writer, and renderer divergences from upstream PDF4QT are recorded in
UPSTREAM_DIVERGENCE.md. Cosmetic Loop-only code does not belong there. Re-run the mapped tests after an authorized sync; a clean merge is not verification.Policy: on-demand GitHub Sync fork
Pull upstream changes only when explicitly requested, through GitHub's Sync fork UI or an intentional local
gh repo sync. Do not automatically merge upstream in CI.When syncing, preserve Loop product and licensing decisions. Take upstream code fixes in shared engine code unless a current Loop ADR or issue says otherwise. Do not push Loop branding, product UX, or release policy upstream.
Conflict handling
Likely conflict files include
README.md,LICENSE,.github/**,CMakeLists.txt, andRELEASES.txt.README.md/LICENSE.RELEASES.txtor a short merge commit message with the upstream SHA.Source-of-truth and generated facts
Resolve documentation conflicts using
architecture-source-of-truth.md. The generatedarchitecture-catalog.jsonemits branch policy names, workflow trigger branches, the Core preflight check catalog, registered repair operations, schema versions, schema kinds, coverage holes, numbered architecture invariants, and CMake test targets. CI runsscripts/generate-architecture-catalogs.py --checkso stale narrative or catalog claims fail before merge.Intentional fork-only behavior is listed in
UPSTREAM_DIVERGENCE.md. Update that register in the same change that introduces a new divergence, and run the preflight corpus plus targeted Core tests before merging an authorized sync.Layout
LoopLibCore/LoopEditor/,LoopLibQuick/PdfTool/PdfTool/,LoopLibCore/LoopEditorPlugins/UnitTests/UnitTests/CMakeLists.txtloop-preflight/docs/adr/,docs/For module placement and build constraints, see
AGENTS.md.Uh oh!
There was an error while loading. Please reload this page.