Repository navigation
Description
Goal and release boundary
Get a Suffolk 1.10.x release candidate onto the development site within 30 days of this planning pass: target October 21, 2026. This is a dev/RC target, not authorization to upgrade partner production servers.
Hard prerequisite: finish, test, and deploy the pending 1.9.x monitoring/deployment release before pivoting deployment work to 1.10.x. Inventory and fixture preparation can proceed in parallel, but the prerequisite must not be bypassed to meet the date.
The accessibility gate is no worse than the approved Suffolk baseline, not identical implementation and not completion of every outstanding accessibility enhancement. Small visual changes may be accepted after review; loss of functionality, keyboard access, announcements, data integrity, or existing security protections is not an acceptable cosmetic difference.
Workstreams and dependencies
- 1.10 migration gate: release and validate the 1.9 monitoring/deployment baseline #82 — Release and validate the pending 1.9 monitoring/deployment baseline. Hard gate for the deployment pivot.
- 1.10 migration matrix: accessibility non-regression against Suffolk's alternative fixes #83 — Differential accessibility matrix: Suffolk fixes versus upstream alternatives.
- 1.10 migration matrix: sanitized partner configs × pinned images × production interviews #84 — Every sanitized partner config × pinned baseline/candidate images × applicable production interviews.
- 1.10 migration matrix: retained patches, hosted integrations, security, and upgrade/rollback #85 — Retained-patch ledger, staged hosting/integrations, security, data migration and rollback.
These are four coordinated workstreams, not replacements for the existing individual bug/implementation issues. Each has case IDs, explicit acceptance criteria, evidence requirements and links to prior work.
Snapshot checked September 21, 2026
| Role | Ref / commit | Meaning |
|---|---|---|
| Suffolk 1.9 source baseline candidate | v1.9.8.post at ad91857aa215fa5461b5e89aa5529e4a24bc4cd0 / 1.9.8.post5 |
Source tip; not proof of what is deployed |
| Existing Suffolk migration work | v1.10.5.post at 7c99a7548bbd6dd4e43a41ca6fa9d2ff4038dc44 |
Partial ports already exist; reconcile rather than start over |
| Upstream reviewed | jhpyle/docassemble at fe3ea09c409f1ab79a5fd92d7681c739246bedb0 / 1.10.11 |
Changelog release September 20, 2026; proposed starting target, subject to security review |
| Actual production image(s) | TBD: capture digest and installed package inventory | Must be measured, not inferred from a branch or latest |
Upstream changelog at the reviewed commit. Pin the eventual candidate's commit and image digest; do not test a floating 1.10.x or latest and release something different.
Proposed sequence
- Days 1–7: close the 1.9 release gate, capture production and accepted-baseline digests, inventory all partner configurations/packages, and nominate workstream owners. Any slippage here is made explicit; it does not silently remove the gate.
- Days 8–14: reconcile the existing 1.10.5 branch against the chosen upstream release, port only retained behavior, build pinned candidate images, and run config/interview and priority accessibility comparisons.
- Days 15–21: resolve regressions; exercise hosted integrations, package/schema upgrades, saved-session continuity, and rollback on disposable environments.
- Days 22–30: deploy the exact candidate to dev, run the agreed observation period and full release matrix, and record an RC go/no-go. Do not deploy to partner production under this issue.
Common evidence contract
Each result records case ID, fixture/config revision, interview package commits, image digest and core distribution versions, runtime versions, execution path, expected and observed behavior, evidence link, reviewer, and disposition. Use pass, baseline failure, candidate regression, blocked, or not applicable with a reason. Missing tests and unavailable services are not passes.
Use the accepted 1.9 release as the main differential baseline; retain current-production evidence to expose regressions introduced by that baseline itself. Stock upstream is a diagnostic control, not the hosted release artifact. Owners, partner inventory, supported browser/AT combinations and staging observation duration still need to be confirmed by the team.
RC acceptance checklist
- 1.10 migration gate: release and validate the 1.9 monitoring/deployment baseline #82 is complete: pending 1.9 release deployed/accepted, baseline digests and rollback evidence recorded.
- All partner config profiles and interview inventories are accounted for, without credentials or user data in fixtures/artifacts.
- 1.10 migration matrix: accessibility non-regression against Suffolk's alternative fixes #83 has no unaccepted accessibility regression; unrelated enhancements remain separately tracked.
- Required custom hosting, observability, provenance and security behavior is retained or replaced with demonstrated equivalent behavior.
- Runtime/dependency, database/schema, saved-session and worker migration tests pass, including a rehearsed rollback.
- The exact pinned candidate runs on dev with linked evidence and an explicit RC decision.
First-pass divergence and migration report
Audit date: September 21, 2026. Method: repository refs, commit/PR history, merge-base delta inventories, and targeted source inspection. This is not a runtime test report or an exhaustive security assessment.
1. What is actually being compared
The Suffolk 1.9 tip is 29 commits ahead and 112 behind the reviewed upstream tip, with upstream 1.9.8 (e71c93989a872bd9350910bd6ea77dc7c363c753) as the common base. The existing Suffolk 1.10.5 branch is 16 ahead and 61 behind the reviewed upstream tip, based on 2bfa55557e262a39f7219341ac54729d957be2e9.
These are history counts, not counts of unported fixes. The 1.9 custom delta includes release bumps and generated bundles; upstream sometimes implements the same behavior with different commits. GitHub's merge-base/three-dot comparison inventories one side's changes, not a complete endpoint-to-endpoint equivalence analysis.
The existing 1.10 branch already changes Docker/release packaging, API permissions, JSON storage and focus-related source/bundles. Reconcile those earlier ports with the newer upstream implementation before adding anything. The late 1.9 monitoring/provenance work is not represented by the corresponding file deltas in that partial branch, so it must be explicitly accounted for rather than assumed present.
Reproducible inventories: 1.9 custom delta from its base, existing 1.10 custom delta from its base.
2. Accessibility: focus first on three actual baseline patch groups
| Baseline behavior | Suffolk implementation | Upstream 1.10.11 alternative | Migration decision / highest-value test |
|---|---|---|---|
| Focus after navigation | #31 / d620319 adds a programmatically focusable question-title fallback; later announcement work changes timing/interaction. | Upstream's September accessibility change selects a form field or question after navigation. Current formatter emits a focusable h1#daMainQuestion; current app code has daFocusMainQuestion(). |
Test replacement, not blind re-port. A01: Continue/Back/review/validation, signature/no-input/autofocus pages, AJAX/socket paths; focus must remain meaningful and not suppress necessary context. Field-vs-heading differences require an outcome decision, not a source-code equality test. |
| Announcing deletion and other messages | #66 / f52f649 initially used hidden heading content. The actual follow-up 1486c4f adds an empty persistent #daSrAnnouncement outside #dabody, filters info/success/warning/danger messages and updates text after 700 ms in AJAX and socket handlers. |
Upstream calls log(word('Deleted'), 'aria') after list/dict deletion, with hidden flash-region output; flash ARIA and focus behavior are also changed. It is not the same persistent-region/timing design. |
High-priority behavioral comparison. A02: repeated identical deletions, rapid actions, final row, failure/cancel, translations and custom alert HTML. Check that speech survives DOM replacement and heading focus, without stale/duplicate announcements. Do not assume the original PR title establishes item-specific announcement text. |
| Required asterisk speech | #75 / 07d9b77 replaces generated stars with <span class="darequiredmarker" aria-hidden="true">, relying on the field's required semantics. |
Reviewed upstream CSS uses pseudo-elements with content: "*" / "" (empty alternative text). |
Alternative exists; equivalence unproven. A03: browser/AT matrix across label/control/layout variants, disabled/conditional state and themes. Prefer upstream if it meets baseline outcomes; adapt the DOM-span patch only where a demonstrated regression requires it. |
This narrows the primary differential work to a small number of behaviors rather than every accessibility issue in the repository. Test the production-served generated assets too: a correct app.js edit does not prove the image serves equivalent minified or embedding bundles.
Additional upstream changes: smoke coverage, not an all-improvements gate
1.10.8 replaces JS-driven radio/checkbox behavior, removes bootstrap-fileinput and generic hidden legends, changes grouping, adds/reworks skip links, flash/spinner/show-if announcements, adjusts navigation/progress semantics, and changes terms/help popovers and the progressive-disclosure recipe. These touch partner templates and JS/CSS even when interviews' Python logic is unchanged. The terms change still uses Bootstrap popovers with a focus trigger; it is not evidence that every proposed alternative widget has been adopted. Source: pinned 1.10.8 changelog and implementation.
Use A04–A07 in #83 to check these surfaces for regression. Existing issues such as combobox behavior, error announcements, grouping, disabled markers and high-contrast rendering remain useful repro sources, not proof that a corresponding patch is present in the 1.9 baseline. Earlier Suffolk contributions already shared with upstream, such as the combobox accessibility merge, are not newly missing fork patches.
PDF accessibility is a separate, already-upstream contribution
The flattened-PDF work is not among the reviewed 1.9 branch's custom file changes; Suffolk PR #64 was closed without merging into that branch. Related Suffolk-contributed code was merged upstream in August, then changed again for 1.10.9.
The newer structure-preserving flattening commit, itself from Suffolk's contribution branch, describes staged pdftk filling/flattening plus pikepdf handling of widget structure, marked content, field state/description and fallback ActualText. Do not attribute all replacement work solely to upstream authorship, and do not copy the older implementation over the newer contribution. Its corpus results are the commit author's reported tests, not this audit's verification.
A08 compares actual generated outputs using partner-representative synthetic forms and supported PDF readers. Preserve appearance, text, reading order, checkbox/radio state and non-editability. PDF/A conversion and DOCX/LibreOffice tag/alt preservation are distinct paths; neither is automatically solved by the flattening change.
3. Other substantive divergences and initial disposition
Legend: retain/adapt = keep the behavior, reconciling existing ports; upstream equivalent = do not duplicate without a failing test; verify = evidence is insufficient to retire the behavior. A port may already be partly present in v1.10.5.post.
| Area / original change | Finding against reviewed upstream | Initial disposition and tests |
|---|---|---|
| Error-email diagnostic context, #71 / 05fc9a4 | Upstream's errors.py provides existing error/history/referrer/user information, but the reviewed function does not include Suffolk's added session/full-request-URL/temp-user/request-ID fields. | Retain/adapt at the new error and worker boundaries, including missing-variable question context. B04/H06. |
| End-to-end request IDs, #73 / 05f4bd1, #77 / 1c0da13 | No equivalent end-to-end implementation identified in this first pass. The original and follow-up PRs describe different coverage, especially worker paths, so do not accept a PR narrative as an end-to-end result. | Retain/adapt nginx generation, trusted propagation and log/email context. Verify web, worker and context cleanup separately. B03/H05. |
| SendGrid JSON variables attachment, #74 / 6fa6461 | Current errors.py still opens the attachment as text; SendGrid adapter directly calls base64.b64encode(flask_attachment.data). |
Concrete port candidate: retain rb/equivalent bytes conversion and test actual transport serialization, not SMTP alone. B04/H06. |
| Installed Git commit provenance, #76 / 1c4b972 | Suffolk adds Package/Install gitcommit, reads pip direct_url.json, changes UI and includes Alembic migration f3a33ced4d95. No matching gitcommit implementation identified upstream in this pass. |
Retain/adapt, reconciling model/module and migration history changes. Same package version at a different Git commit is a required case. B05/H04. |
| JSON write transaction recovery, e432d27 | Upstream moved implementation to jsonstorage/helpers.py; its write function still commits without local rollback handling. Global/request cleanup may affect behavior and must be tested. | Preserve recovery intent; verify exact placement in the hook/session lifecycle. Failure followed by an unrelated successful write, including remote snapshots/Supabase. This is not the duplicate-ID root-cause fix. H03. |
| Read-only package access and API-key permission creation, #24, #35 | 1.10.6 documents read_packages; current API helper stores permissions and POST handler validates them with an admin authorization gate. |
Upstream equivalent present. Prefer it; retain tests for new/legacy keys, read-vs-mutation and unauthorized permission grants. Reconcile any duplicate earlier 1.10 port. H02. |
| Flask/WebSocket compatibility, #29 / 11776f6 | Upstream 1.9.12 records a fix, and reviewed 1.10.11 webapp dependencies pin Flask-SocketIO 5.6.1. | Upstream requirement present. Do not replay an old pin; validate installed dependency resolution and Monitor/WebSocket behavior. H01/H08. |
| Suffolk distribution/source ownership, 77d5246, release workflows 7c2dbae and ea937a6 | Suffolk uses its own core Python distribution names and GHCR/PyPI publication/update behavior. Upstream naturally publishes its own distributions, not a replacement for Suffolk's release provenance. | Retain/adapt naming, dependencies, source affinity, updater safeguards and multi-architecture builds. Test that neither upgrade nor package installation silently replaces fork core code. B01/H01. |
| Hosting timings and build-time work: c8250d7, 5b95a11, 643998a, 3a1d476, 96f7820 | Fork intent is 300-second nginx/uWSGI read timeout, 1,800-second supervisor stop allowance, build-time ownership/fonts and startup timing diagnostics. The newer OS/runtime does not by itself demonstrate equivalent hosted behavior. | Retain required behavior/adapt implementation. Check actual service roles, mounted volumes, orchestrator grace periods, font output and measured startup/backup times before retiring patches. H07. |
| Custom nginx/security packaging and rotation: e9e926c, #32 / d5537e9, #69 / 4d1d78 | Suffolk changed the nginx package source and reopen command, then removed app-log maxsize to avoid unscheduled uWSGI restarts. #32 explicitly says the reopen fix follows Suffolk's package choice rather than upstream's layout. |
Retain/adapt, not wholesale cherry-pick. Choose a currently appropriate nginx build and compatible reopen mechanism; verify rotation, shipping, retention and restart behavior. Do not blindly downgrade a newer image to an old nginx pin. H02/H05/H07. |
Supabase, log shipping and Grafana are deployment/integration requirements, not evidence that a distinct in-repository patch exists for each service. Their full configuration was not available in this audit. #85 inventories the real topology and tests those services with staging credentials, separately from #84's credential-free config library.
4. Security requirements must survive dependency refreshes
Suffolk's #30 dependency update set NLTK 3.9.4, Pillow 12.2.0 and Tornado 6.5.5 for security reasons. The reviewed upstream base manifest and webapp manifest show:
| Dependency | Observed upstream state | Required migration decision |
|---|---|---|
| NLTK | 3.9.2, below Suffolk's 3.9.4 update; 1.10.7 explicitly records a downgrade to avoid requiring a system upgrade | Hold point: reconcile a compatible version meeting current security requirements. Do not assume newer docassemble preserves the security floor. |
| Pillow | 12.3.0, newer than Suffolk's 12.2.0 pin | Do not reapply the older pin; review/scan the resolved image and test affected output. A higher number is not a complete vulnerability assessment. |
| Tornado | No direct pin in the reviewed manifests | Inspect resolved/transitive dependencies and image inventory. Absence from a manifest is not proof of removal or remediation. Retain an appropriate constraint if it is still installed and needed. |
Also preserve newer upstream protections: 1.10.2 documents /logfile sanitization and Twilio /sms verification; 1.10.10 documents LDAP login input sanitization. Reapplying old monolithic server code could inadvertently remove newer security behavior. Test relevant configured endpoints and permissions after porting. This audit identifies source/version differences, not production exploitability or a current-CVE clean bill of health.
5. Compatibility gaps beyond the custom patches
The changelog identifies migration surfaces that a 'mostly visual changes' assumption would miss:
- Runtime and data: upstream's Docker image changes after 1.9.8 include Ubuntu 24.04→26.04, PostgreSQL 16→18, Python 3.12→3.14, and
unoconv→unoserver. 1.10.6 separately requires Python >=3.12 for the Python packages. Test the actual candidate image and external Supabase version, not just the application number. Rehearse database migration/restore; an image downgrade does not undo a database major-version or schema change. - Code and state: 1.10.0 introduces blueprint/hook/module reorganization, SQLAlchemy model changes and Celery signatures. Partner imports of undocumented internals, custom worker code and saved-session serialization require testing even if documented interview syntax remains stable.
- Known breaking extension point: 1.10.8 adds a third
itemargument to_edit_button()and_delete_button(). Inventory partner/AssemblyLine overrides and calls; do not assume they are compatible merely because ordinary interviews render. - Configured presentation: custom
alert container html/alert html, JS tied to removed plugins, file inputs, address autocomplete and the new label application of radio/checkbox CSS classes deserve targeted coverage. A small screenshot difference is acceptable only after functional/accessibility review.
Pending proposals/topic branches outside the reviewed 1.9 baseline, such as the session-list endpoint work in #79, are scope decisions rather than automatically required carry-forward patches. Do not turn this migration into a merge of every outstanding branch.
6. Test-harness findings and recommended migration order
ALKiln's reviewed isolated server action already supports DOCASSEMBLE_IMAGE and CONFIG_CONTENTS, the YAML contents rather than a filename. Use it to run all sanitized partner profiles against pinned baseline/candidate images; use stock upstream as an attribution control.
The production-interview runner from #60 was moved to DevOpsScripts. Its current reviewed source hard-codes latest, clones default branches, derives repositories from a single org/name convention, excludes one package and uses load-only fallback scenarios when tests are missing. These are coverage/reproducibility limits, not reasons to build a duplicate runner. #84 makes them explicit and asks for a manifest-driven, pinned, bounded version.
Recommended port order after the 1.9 gate: reconcile release identity/runtime/security requirements first; then transaction/schema and hosted lifecycle behavior; then monitoring, error email and installed-commit provenance; then run the accessibility alternatives before deciding whether any of the three baseline accessibility patch groups still need custom code. Keep upstream's newer PDF work and authorization fixes unless a specific test demonstrates a regression.
Limits: no actual partner config files, production image inventory or deployment environment were accessed; no images were built, packages installed, browser/AT sessions run, generated PDFs evaluated, integrations exercised or production deployments made. 'No equivalent identified' is a targeted first-pass finding. The four linked issues turn the remaining uncertainty into named tests and explicit release decisions.
Metadata
Metadata
Assignees
Labels
Type
Fields
Start date
Target date
Size/effort
Activity