jchapman/Immich-Bridge

Watch

Fork 0

First release readiness checklist #27

New issue

Open

opened 2026-11-02 01:55:36 +00:00 by jchapman · 0 comments

jchapman commented

2026-11-02 01:55:36 +00:00

Owner

Implementation will be handled in the release-preparation work. Creating this issue does not start UI changes or authorize a new build/deployment. The release version is still to be decided.

Release prerequisites

Verify the fresh pilot.4 production preview completes with complete diagnostics, zero errors and zero pending assets; confirm the 19 unmatched files excluded by options are reported as skips. Follow #26.
Complete and review the actual production import, including final accounting, skipped-item reasons, timing and available worker/server captures. Preserve the distinction between preview timing and actual transfer timing.
Review remaining open issues and resolve any other release blockers. The unfinished virus/malware scanning feature in #12 is explicitly not a release blocker under the agreed policy below.
Complete the normal release checks/tests for the chosen immutable revision and supported platforms. Do not treat native ARM64 pilot validation as completion of the separate full release matrix.
Agree the first non-pilot version and prepare release notes covering supported inputs, tested compatibility and known limitations.

Architecture releases and visible CI validation

Produce release artifacts/images for both ARM64 (linux/arm64) and AMD64 (linux/amd64), using the same agreed release version and reviewed source revision.
Finish configuring the CI runners so every required release-validation job can actually run, including the supported architecture matrix; final release validation must not remain indefinitely queued or pending.
Run the complete required release validation in CI against the exact release revision. Local tests and native pilot checks are supporting evidence, not a substitute for the final CI validation.
Make completed validation results visible to the intended release audience. Link successful CI runs/checks from the release notes and provide accurate validation-status links or badges in the README, so people can see what ran and passed.

Mobile wizard

Make all wizard step indicators the same height on mobile.
Provide appropriate padding around the words so labels are not squished against the sides.
Check the complete wizard on narrow mobile screens, including wrapped labels, navigation controls and long text.

Application footer

Keep the footer compact and readable on mobile. Proposed layout:

Immich Bridge · {running server version}
Help · Support · Data & privacy · Source & licenses

Display the authoritative running backend version; do not infer it solely from cached browser assets.
Make Version/About open details with the build revision, packaged Immich-Go version, credits and release notes.
Help: link to the user guide for exports, uploads/resuming, previews, imports and common problems.
Support: distinguish help from this instance's administrator from reporting application bugs; provide administrator contact when configured and a route to report a bug.
Data & privacy: explain actual storage, configured retention/deletion behavior, private logs, email notifications and scanning capabilities. Avoid promises that do not match the running configuration.
Source & licenses: provide access to source for the deployed Bridge version and its modified Immich-Go component, with the corresponding licenses and credits.
Allow links to wrap with comfortable spacing and padding on mobile.

Documentation source of truth

Make the version-controlled, in-repository documentation the authoritative description of the application, supported behavior and operation for each release.
Keep those documents aligned with what actually ships. Release preparation does not require reconciling or publishing the original 96-page requirements document, and that document will not be included in the release.
Capture worthwhile omissions or additional ideas found in the original requirements as repository issues or Project board items, where they can be reviewed and prioritized as future work.

Repository and release cleanup

Review obsolete pilot references, superseded examples and temporary development material; clean up what is no longer needed while preserving relevant history and ongoing scanner work.
Make the README, examples, version references and release instructions agree with the actual release behavior and supported scope.
Verify release artifacts, immutable image references, version information, license notices and matching source are consistent.

README and application screenshots

Include a brief AI-assisted development disclosure in the README. Accurately describe the maintainer's human-defined requirements, review of every line of application code, extensive functional testing and direct UI/functional code contributions. Use "primarily" rather than an unmeasured percentage, and retain maintainer responsibility for releases. This is the maintainer's account of the development process, not a claim of an independent audit.

Suggested wording:

Immich Bridge was developed primarily with AI coding tools, guided by requirements I defined and refined throughout development. I reviewed every line of application code, extensively tested its functionality, and contributed UI and functional changes directly. As maintainer, I remain responsible for the releases.

Write and edit the main README in a natural, human voice: readable, descriptive and informative. Explain what Bridge does, who it is for, the migration experience and how to get started, without generic AI-style filler or an overly technical presentation.
Keep detailed configuration and operational instructions in the administrator documentation, with clear links from the README.
Include useful, representative screenshots of the application in the README where they help explain the product.
Give screenshots particular attention in the end-user documentation: illustrate relevant steps and results with the actual application screens, matching the released UI and terminology.
Use readable screenshots with helpful captions/alternative text and suitable sample or redacted data; refresh them after the release UI changes.
Call out that only Google Photos (Takeout) has been implemented at this time. All other formats (iCloud, Local Folder, etc.) are still to be implemented.

User documentation

Write for end users moving their photos. Use plain language, explain what they should see and do, and avoid assuming system administration or command-line knowledge.
Review the full user journey: connect an Immich account, prepare a Google Takeout export, upload/resume all ZIP parts, analyze, review warnings, preview and explicitly import.
Explain processed versus newly uploaded, intentional skips versus genuinely unfinished assets, and how to inspect affected files.
Document background processing and optional completion email, Stop behavior, interrupted tasks, collection deletion and keeping/checking original exports.
Explain troubleshooting and the difference between a support report and a private importer log.

System administrator documentation

Write for system administrators hosting and operating Bridge. Provide precise prerequisites, commands, configuration and operational explanations appropriate to that audience. Keep this guidance distinct from the end-user instructions.
Verify installation prerequisites, supported/tested dependency versions, configuration examples and deployment instructions.
Document persistent storage, permissions, resource requirements, worker isolation, networking and required access.
Document credentials/configuration handling, backups, retention/deletion behavior and operator responsibilities.
Document upgrades/rollback, health/readiness checks, active-task restart behavior, logs and troubleshooting.
Check instructions from the viewpoint of someone who has not followed the development chats.

Security scanning policy and disclosure

Explicitly state that archive virus/malware scanning is unfinished under #12. Do not describe the application as scanning uploads until that capability is implemented and validated.
Document the current safeguards and remaining limitations accurately.
Link the limitation from Data & privacy and explain it where users choose to upload/import; the footer must not be its only disclosure.
Make the release decision with the agreed policy: users may choose to use Bridge without virus/malware scanning, and this unfinished feature alone will not hold the release.

Current context

Pilot 0.1.3-pilot.4, with modified importer 0.32.0-bridge.6, is deployed. Local testing of the same three Takeout ZIPs accounted for 33,410 assets with zero errors/pending and confirmed all 19 unmatched source files as explicit skips. Native ARM64 tests/security gates and deployment checks passed. The separate full-matrix source CI was last observed waiting for runners. The fresh production preview is running per the user's latest report; successful production preview/import validation is not yet recorded.

Related work: #26 (preview reliability and accounting), #12 (unfinished security scanning).

Prepare the first non-pilot release of Immich Bridge for end users and system administrators. This issue is the shared release checklist and should become the place to track additional release-preparation work. Implementation will be handled in the release-preparation work. Creating this issue does not start UI changes or authorize a new build/deployment. The release version is still to be decided. ## Release prerequisites - [ ] Verify the fresh pilot.4 production preview completes with complete diagnostics, zero errors and zero pending assets; confirm the 19 unmatched files excluded by options are reported as skips. Follow #26. - [ ] Complete and review the actual production import, including final accounting, skipped-item reasons, timing and available worker/server captures. Preserve the distinction between preview timing and actual transfer timing. - [ ] Review remaining open issues and resolve any other release blockers. The unfinished virus/malware scanning feature in #12 is explicitly not a release blocker under the agreed policy below. - [ ] Complete the normal release checks/tests for the chosen immutable revision and supported platforms. Do not treat native ARM64 pilot validation as completion of the separate full release matrix. - [ ] Agree the first non-pilot version and prepare release notes covering supported inputs, tested compatibility and known limitations. ## Architecture releases and visible CI validation - [ ] Produce release artifacts/images for both **ARM64 (`linux/arm64`)** and **AMD64 (`linux/amd64`)**, using the same agreed release version and reviewed source revision. - [ ] Finish configuring the CI runners so every required release-validation job can actually run, including the supported architecture matrix; final release validation must not remain indefinitely queued or pending. - [ ] Run the complete required release validation in CI against the exact release revision. Local tests and native pilot checks are supporting evidence, not a substitute for the final CI validation. - [ ] Make completed validation results visible to the intended release audience. Link successful CI runs/checks from the release notes and provide accurate validation-status links or badges in the README, so people can see what ran and passed. ## Mobile wizard - [ ] Make all wizard step indicators the same height on mobile. - [ ] Provide appropriate padding around the words so labels are not squished against the sides. - [ ] Check the complete wizard on narrow mobile screens, including wrapped labels, navigation controls and long text. ## Application footer Keep the footer compact and readable on mobile. Proposed layout: > **Immich Bridge · {running server version}** > Help · Support · Data & privacy · Source & licenses - [ ] Display the authoritative running backend version; do not infer it solely from cached browser assets. - [ ] Make Version/About open details with the build revision, packaged Immich-Go version, credits and release notes. - [ ] **Help:** link to the user guide for exports, uploads/resuming, previews, imports and common problems. - [ ] **Support:** distinguish help from this instance's administrator from reporting application bugs; provide administrator contact when configured and a route to report a bug. - [ ] **Data & privacy:** explain actual storage, configured retention/deletion behavior, private logs, email notifications and scanning capabilities. Avoid promises that do not match the running configuration. - [ ] **Source & licenses:** provide access to source for the deployed Bridge version and its modified Immich-Go component, with the corresponding licenses and credits. - [ ] Allow links to wrap with comfortable spacing and padding on mobile. ## Documentation source of truth - [ ] Make the version-controlled, in-repository documentation the authoritative description of the application, supported behavior and operation for each release. - [ ] Keep those documents aligned with what actually ships. Release preparation does not require reconciling or publishing the original 96-page requirements document, and that document will not be included in the release. - [ ] Capture worthwhile omissions or additional ideas found in the original requirements as repository issues or Project board items, where they can be reviewed and prioritized as future work. ## Repository and release cleanup - [ ] Review obsolete pilot references, superseded examples and temporary development material; clean up what is no longer needed while preserving relevant history and ongoing scanner work. - [ ] Make the README, examples, version references and release instructions agree with the actual release behavior and supported scope. - [ ] Verify release artifacts, immutable image references, version information, license notices and matching source are consistent. ## README and application screenshots - [ ] Include a brief AI-assisted development disclosure in the README. Accurately describe the maintainer's human-defined requirements, review of every line of application code, extensive functional testing and direct UI/functional code contributions. Use "primarily" rather than an unmeasured percentage, and retain maintainer responsibility for releases. This is the maintainer's account of the development process, not a claim of an independent audit. Suggested wording: > Immich Bridge was developed primarily with AI coding tools, guided by requirements I defined and refined throughout development. I reviewed every line of application code, extensively tested its functionality, and contributed UI and functional changes directly. As maintainer, I remain responsible for the releases. - [ ] Write and edit the main README in a natural, human voice: readable, descriptive and informative. Explain what Bridge does, who it is for, the migration experience and how to get started, without generic AI-style filler or an overly technical presentation. - [ ] Keep detailed configuration and operational instructions in the administrator documentation, with clear links from the README. - [ ] Include useful, representative screenshots of the application in the README where they help explain the product. - [ ] Give screenshots particular attention in the end-user documentation: illustrate relevant steps and results with the actual application screens, matching the released UI and terminology. - [ ] Use readable screenshots with helpful captions/alternative text and suitable sample or redacted data; refresh them after the release UI changes. - [ ] Call out that only Google Photos (Takeout) has been implemented at this time. All other formats (iCloud, Local Folder, etc.) are still to be implemented. ## User documentation - [ ] Write for **end users** moving their photos. Use plain language, explain what they should see and do, and avoid assuming system administration or command-line knowledge. - [ ] Review the full user journey: connect an Immich account, prepare a Google Takeout export, upload/resume all ZIP parts, analyze, review warnings, preview and explicitly import. - [ ] Explain processed versus newly uploaded, intentional skips versus genuinely unfinished assets, and how to inspect affected files. - [ ] Document background processing and optional completion email, Stop behavior, interrupted tasks, collection deletion and keeping/checking original exports. - [ ] Explain troubleshooting and the difference between a support report and a private importer log. ## System administrator documentation - [ ] Write for **system administrators** hosting and operating Bridge. Provide precise prerequisites, commands, configuration and operational explanations appropriate to that audience. Keep this guidance distinct from the end-user instructions. - [ ] Verify installation prerequisites, supported/tested dependency versions, configuration examples and deployment instructions. - [ ] Document persistent storage, permissions, resource requirements, worker isolation, networking and required access. - [ ] Document credentials/configuration handling, backups, retention/deletion behavior and operator responsibilities. - [ ] Document upgrades/rollback, health/readiness checks, active-task restart behavior, logs and troubleshooting. - [ ] Check instructions from the viewpoint of someone who has not followed the development chats. ## Security scanning policy and disclosure - [ ] Explicitly state that archive virus/malware scanning is unfinished under #12. Do not describe the application as scanning uploads until that capability is implemented and validated. - [ ] Document the current safeguards and remaining limitations accurately. - [ ] Link the limitation from Data & privacy and explain it where users choose to upload/import; the footer must not be its only disclosure. - [ ] Make the release decision with the agreed policy: users may choose to use Bridge without virus/malware scanning, and this unfinished feature alone will not hold the release. ## Current context Pilot **0.1.3-pilot.4**, with modified importer **0.32.0-bridge.6**, is deployed. Local testing of the same three Takeout ZIPs accounted for 33,410 assets with zero errors/pending and confirmed all 19 unmatched source files as explicit skips. Native ARM64 tests/security gates and deployment checks passed. The separate full-matrix source CI was last observed waiting for runners. The fresh production preview is running per the user's latest report; successful production preview/import validation is not yet recorded. Related work: #26 (preview reliability and accounting), #12 (unfinished security scanning).

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

jchapman/Immich-Bridge#27

No description provided.

Rows
Columns