diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index bbcbbe7d..b83cc681 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -16,5 +16,12 @@ A clear and concise description of what you want to happen. **Describe alternatives you've considered** A clear and concise description of any alternative solutions or features you've considered. +**Expected outcome and acceptance** +How would a user or maintainer verify that this solves the problem? + +**Constraints and scope** +Note deployment, compatibility or security constraints, and anything deliberately out of scope. +Release scope and milestone assignment are maintainer decisions, not commitments made by this request. + **Additional context** Add any other context or screenshots about the feature request here. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..5c5faa6e --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,25 @@ +## Problem and outcome + +What user problem, security risk or operational gap does this address? Why this approach? + +## Scope and links + +Related issue/proposal: +Target milestone (if accepted into a release): + +Use `Fixes #...` for completed work or `Refs #...` for partial work. Small fixes and +dependency updates do not need a duplicate planning issue. + +## Validation + +- Exact tested revision and checks/results: +- Regression/acceptance coverage: +- Compatibility, upgrade and security impact: +- Remaining deployment-specific checks or explicit limitations: + +## Delivery + +Merging implements the change; it does not publish a versioned release. Link the +release-readiness issue when relevant. Record deferred work and the reason there. + +See [the planning workflow](https://github.com/bifrost0x/webssh/blob/main/docs/project-planning.md). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 399de6b7..1d1589dd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,6 +7,7 @@ Thanks for your interest in contributing! This project is open to contributions - [Report a Bug](https://github.com/bifrost0x/webssh/issues/new?template=bug_report.md) - [Request a Feature](https://github.com/bifrost0x/webssh/issues/new?template=feature_request.md) - [Security Issues](SECURITY.md) - Please don't open public issues for vulnerabilities +- [Roadmap](ROADMAP.md) and [planning workflow](docs/project-planning.md) ## Getting Started @@ -99,6 +100,12 @@ Feature requests are welcome! Please include: 2. **Open an issue first** for larger changes - Let's discuss the approach 3. **Small PRs are better** - Easier to review and merge +For substantial work, state the user problem, expected outcome and acceptance criteria +in the linked issue/proposal. Include the reason for the chosen approach, validation, +compatibility/security impact and remaining rollout checks in the PR. Maintainers assign +accepted work to a release milestone; merging does not itself publish a release. +See the [planning and release workflow](docs/project-planning.md) for the lightweight cycle. + #### Development Workflow 1. Fork the repository @@ -165,10 +172,10 @@ If your change touches authentication, encryption, or session handling, please n #### Public Repository Hygiene -Everything committed here is published. Do not commit local agent instructions, -AI-tool configuration, private review notes, development captures, temporary -test output, workstation paths, credentials, or unreferenced media. Keep reusable -product and operator documentation in the existing public documentation areas. +Everything committed here is published. Do not commit local development +instructions, tool configuration, private notes, development captures, +temporary test output, workstation paths, credentials, or unreferenced media. +Keep reusable product and operator documentation in the public documentation areas. Run the same repository guard used by CI before submitting: diff --git a/README.md b/README.md index b5e3696b..d578cc75 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,7 @@

Product site · Documentation · + Roadmap · Container image · Discussions

@@ -272,6 +273,9 @@ requests and published automatically after changes reach `main`. Additional project views: +- [Roadmap and current release focus](ROADMAP.md) +- [Project history and documented decisions](docs/project-history.md) +- [Planning, milestones and release workflow](docs/project-planning.md) - [Product site](https://bifrost0x.github.io/webssh/) - [Interactive code graph](https://bifrost0x.github.io/webssh/code-graph/) - [Container image](https://github.com/bifrost0x/webssh/pkgs/container/webssh) diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 00000000..82b7fd58 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,87 @@ +# WebSSH Roadmap + +WebSSH is a self-hosted SSH and file workspace. This roadmap explains the direction, +the current release focus, and the evidence behind completed work. It is not a release-date +promise or a replacement for issues, pull requests, and release notes. + +Planning baseline: **2026-10-03**, commit +[`dc3d9bf`](https://github.com/bifrost0x/webssh/commit/dc3d9bf26f57cbeb440227afe13f9635c4d9f258). +Check the linked GitHub items for newer status. + +## Product direction + +- Keep terminals, files, commands, diagnostics, and notes aligned with the active server. +- Preserve explicit authentication, ownership, host-trust, network-policy and resource boundaries. +- Make the same workspace useful on mobile devices and multi-pane desktops. +- Keep deployment, upgrades, recovery and container publication verifiable and self-hosted. + +These themes summarize the existing product and published release history; they do not +add new feature commitments. + +## Now: consolidate the post-2.4 changes + +**Proposed next release: v2.5.0.** No release date is committed. Scope and version remain +subject to maintainer review. The latest published release at this baseline is +[v2.4.0](https://github.com/bifrost0x/webssh/releases/tag/v2.4.0). + +| Outcome | Implementation state at the baseline | Remaining delivery work | +|---|---|---| +| Optional Warpgate gateway authentication | [#238](https://github.com/bifrost0x/webssh/pull/238) merged; request [#237](https://github.com/bifrost0x/webssh/issues/237) closed | Final-candidate real-protocol acceptance; earlier evidence is revision-specific | +| Workspace continuity and tmux directory synchronization | [#231](https://github.com/bifrost0x/webssh/pull/231), [#233](https://github.com/bifrost0x/webssh/pull/233), [#234](https://github.com/bifrost0x/webssh/pull/234), [#235](https://github.com/bifrost0x/webssh/pull/235), [#236](https://github.com/bifrost0x/webssh/pull/236) merged | Focused multi-session and mobile canary | +| Correct paste input and saved transcripts | [#239](https://github.com/bifrost0x/webssh/pull/239), [#241](https://github.com/bifrost0x/webssh/pull/241) merged | Verify paste/control input and transcript behavior on the candidate | +| Clearer connection review and file actions | [#242](https://github.com/bifrost0x/webssh/pull/242) merged | Connection/key review and file-workspace smoke tests | +| Reviewed dependency and repository maintenance | [#232](https://github.com/bifrost0x/webssh/pull/232), [#243](https://github.com/bifrost0x/webssh/pull/243), [#246](https://github.com/bifrost0x/webssh/pull/246), [#247](https://github.com/bifrost0x/webssh/pull/247) merged | Fresh exact-candidate CI and both native image scans | + +All of these changes are **merged but not included in the v2.4.0 tag**. +The [fixed-baseline comparison](https://github.com/bifrost0x/webssh/compare/v2.4.0...dc3d9bf26f57cbeb440227afe13f9635c4d9f258) +contains 13 merged PRs. Baseline [CI and native image publication](https://github.com/bifrost0x/webssh/actions/runs/37064319620) +passed; this does not complete every deployment-specific acceptance check. + +The open [release-readiness issue #248](https://github.com/bifrost0x/webssh/issues/248) +is the delivery gate. It remains open until candidate validation, release publication, +and versioned-image verification have evidence. A milestone is not shipped merely because +its implementation PRs are merged. + +## Next: choose from verified feedback + +After this release, select a small scope from reproducible bugs, user feedback and validated +security/dependency findings. State the benefit, priority reason and acceptance criteria in +an issue before assigning substantial work to the next milestone. + +No additional feature release, date or large architecture migration is committed here. +Urgent security fixes may take a separate patch path rather than wait for a feature release; +follow [SECURITY.md](SECURITY.md) for private vulnerability reporting. + +## Later: proposals are not promises + +Keep exploratory integration and architecture proposals in +[Discussions](https://github.com/bifrost0x/webssh/discussions) until scope and constraints +are reviewed. The PostgreSQL proposal in [#62](https://github.com/bifrost0x/webssh/issues/62), +for example, was converted to a discussion; its closure is not evidence of PostgreSQL support. +An external database alone would not solve process-local SSH state or make multi-worker/HA +deployment supported. Do not promote an idea into a promised release by listing it here. + +## Completed direction + +| Stage | Delivered focus | +|---|---| +| [v1.0.0](https://github.com/bifrost0x/webssh/releases/tag/v1.0.0) | First official terminal/SFTP, tmux, multi-user and Docker baseline | +| [v1.1.0](https://github.com/bifrost0x/webssh/releases/tag/v1.1.0) | Threaded runtime, modern identity, isolation, backup/restore and supply-chain gates | +| [v1.2.0](https://github.com/bifrost0x/webssh/releases/tag/v1.2.0) - [v1.3.0](https://github.com/bifrost0x/webssh/releases/tag/v1.3.0) | Active-session diagnostics, navigation, commands, host organization and key maintenance | +| [v2.0.0](https://github.com/bifrost0x/webssh/releases/tag/v2.0.0) | Authentication assurance and responsive contextual workspace | +| [v2.1.0](https://github.com/bifrost0x/webssh/releases/tag/v2.1.0) | Opt-in encrypted SMB and post-redesign workflow fixes | +| [v2.2.0](https://github.com/bifrost0x/webssh/releases/tag/v2.2.0) - [v2.2.1](https://github.com/bifrost0x/webssh/releases/tag/v2.2.1) | Terminal-first mobile, GitHub authentication and focused touch-scrolling correction | +| [v2.3.0](https://github.com/bifrost0x/webssh/releases/tag/v2.3.0) | Mobile/input, account-linking, notes/transfers and validated security remediation | +| [v2.4.0](https://github.com/bifrost0x/webssh/releases/tag/v2.4.0) | Responsive high-output multi-session recovery, directory sync and verified image promotion | + +## How this is maintained + +- [Project history](docs/project-history.md): what shipped, documented reasons and lessons. +- [Planning and release workflow](docs/project-planning.md): how issues, PRs and milestones fit together. +- [Milestones](https://github.com/bifrost0x/webssh/milestones): native release grouping, when configured. +- [Retrospective mapping](docs/release-history.json): verified release/PR/issue membership and prepared milestone descriptions. + +The historical mapping was reconstructed on 2026-10-03. It does not imply that these +milestones or this roadmap existed at the time. Actual GitHub milestone creation and +closure dates must remain unchanged; original publication dates are recorded as evidence. +Existing GitHub Projects are not replaced or reorganized by this roadmap. diff --git a/docs/project-history.md b/docs/project-history.md new file mode 100644 index 00000000..3963458b --- /dev/null +++ b/docs/project-history.md @@ -0,0 +1,93 @@ +# WebSSH Project History + +This retrospective explains what shipped and why the documented changes mattered. +It is reconstructed from public releases, PR descriptions, issue links and Git ancestry, +not from an original project plan. Reconstruction date: **2026-10-03**. + +## Reading the evidence + +- **Delivered:** the published tag contains the implementation's merge commit. +- **Documented reason:** a source explicitly describes the problem, root cause or goal. +- **Retrospective lesson:** an interpretation for future planning, not a claim about a + decision that was documented at the time. +- Historical validation is evidence reported in the linked items, not tests rerun today. + A historical release does not prove acceptance on every operator's real environment. + +Release dates below are GitHub publication dates. They are not reconstructed deadlines. +Backfilled milestone creation/closure metadata must reflect the actual backfill operation. + +## Before the first official release + +The available Git history starts on **2026-01-23** with +[`2fcd38a`](https://github.com/bifrost0x/webssh/commit/2fcd38ad12cc1cf6d36563aace320ecb8a94e040). +The initial commit mentions `v1.0.0`, but that message is not a published GitHub Release. +The first official published release is **v1.0.0 on 2026-07-23**. + +Early work already mixed security fixes, dependency updates and usability: +[#5](https://github.com/bifrost0x/webssh/pull/5) hardened logging, passwords, profiles and +network controls; [#20](https://github.com/bifrost0x/webssh/pull/20) addressed SSRF, login +timing, upload limits and a Socket.IO dependency issue; +[#36](https://github.com/bifrost0x/webssh/pull/36) added persistent tmux, replay and scrollback. +These belong to the first official release baseline, not invented pre-1.0 release milestones. + +## Published release stages + +| Release / published | Delivered outcome | Documented problem or purpose | Verified merged PRs first shipped here | +|---|---|---|---:| +| [v1.0.0](https://github.com/bifrost0x/webssh/releases/tag/v1.0.0) / 2026-07-23 | Multi-user terminal/SFTP workspace, tmux, keys, profiles and Docker deployment | Give homelabs and small teams browser access without an external service | 35 | +| [v1.1.0](https://github.com/bifrost0x/webssh/releases/tag/v1.1.0) / 2026-08-03 | Native threaded runtime, passkeys/OIDC, bounded operations, trust/isolation, backup/restore and supply-chain gates | [#60](https://github.com/bifrost0x/webssh/pull/60): the old dependency/runtime set constrained security updates and failure boundaries needed hardening; [#71](https://github.com/bifrost0x/webssh/pull/71): recoverable native admin backup/restore | 10 | +| [v1.2.0](https://github.com/bifrost0x/webssh/releases/tag/v1.2.0) / 2026-08-11 | Active-session Linux telemetry, SFTP, diagnostics, host groups/favorites and navigation | Keep server administration in one focused session workspace; [#81](https://github.com/bifrost0x/webssh/pull/81) addresses the navigation requests [#75](https://github.com/bifrost0x/webssh/issues/75), [#76](https://github.com/bifrost0x/webssh/issues/76), [#77](https://github.com/bifrost0x/webssh/issues/77) | 13 | +| [v1.3.0](https://github.com/bifrost0x/webssh/releases/tag/v1.3.0) / 2026-08-12 | Safe active-session command insertion, host ordering and in-place key replacement | Make recurring administration faster and saved connections more predictable; [#94](https://github.com/bifrost0x/webssh/pull/94), [#96](https://github.com/bifrost0x/webssh/pull/96), [#97](https://github.com/bifrost0x/webssh/pull/97), [#98](https://github.com/bifrost0x/webssh/pull/98) | 6 | +| [v2.0.0](https://github.com/bifrost0x/webssh/releases/tag/v2.0.0) / 2026-08-21 | Responsive workspace and Security/Admin Centers; TOTP, LDAP/OIDC and action-bound assurance | [#124](https://github.com/bifrost0x/webssh/pull/124): protected changes need assurance appropriate to the account and sensitive action; contextual tools must follow the active session | 16 | +| [v2.1.0](https://github.com/bifrost0x/webssh/releases/tag/v2.1.0) / 2026-08-24 | Opt-in encrypted SMB sources and cross-source transfers, versioned Wiki, SFTP/theme/login fixes | [#140](https://github.com/bifrost0x/webssh/pull/140): extend the file workspace without weakening ownership, target allowlisting and mutation boundaries; [#132](https://github.com/bifrost0x/webssh/pull/132), [#136](https://github.com/bifrost0x/webssh/pull/136): correct post-2.0 regressions | 9 | +| [v2.2.0](https://github.com/bifrost0x/webssh/releases/tag/v2.2.0) / 2026-08-30 | Terminal-first mobile/tablet UI, managed GitHub authentication, unified management, MFA/file hardening | [#163](https://github.com/bifrost0x/webssh/issues/163)/[#164](https://github.com/bifrost0x/webssh/pull/164): Android touch scrolling was unusable; [#154](https://github.com/bifrost0x/webssh/issues/154)/[#158](https://github.com/bifrost0x/webssh/pull/158): consolidate management workspaces | 15 | +| [v2.2.1](https://github.com/bifrost0x/webssh/releases/tag/v2.2.1) / 2026-08-30 | Focused normal-history scrolling correction and direct mobile session tools | [#165](https://github.com/bifrost0x/webssh/pull/165): synthetic wheel events passed a unit check but did not trigger actual browser scrollback | 1 | +| [v2.3.0](https://github.com/bifrost0x/webssh/releases/tag/v2.3.0) / 2026-09-11 | Session-duration controls, verified OIDC linking, mobile/copy/notes/transfer fixes and security remediation | [#202](https://github.com/bifrost0x/webssh/pull/202): validated repository security findings; [#208](https://github.com/bifrost0x/webssh/issues/208)/[#209](https://github.com/bifrost0x/webssh/pull/209): linking friction without weakening stable issuer/subject binding; [#210](https://github.com/bifrost0x/webssh/issues/210)/[#211](https://github.com/bifrost0x/webssh/pull/211): mobile input regression remained | 27 | +| [v2.4.0](https://github.com/bifrost0x/webssh/releases/tag/v2.4.0) / 2026-09-21 | High-output multi-session rendering/recovery, terminal/files sync, hardened remote work and native-image release gates | [#221](https://github.com/bifrost0x/webssh/pull/221): hidden-pane rendering delayed ACKs and caused reconnect loops; [#223](https://github.com/bifrost0x/webssh/pull/223)-[#226](https://github.com/bifrost0x/webssh/pull/226): verify immutable image candidates without breaking deployment compatibility | 16 | + +The 148 PRs in these release stages are assigned by their **first tagged inclusion**, +not by the week in which they merged. The machine-readable +[release history](release-history.json) lists every PR number, tag SHA, release URL, +comparison and verified issue-to-implementation link. Direct commits are covered by the +Git comparisons even though they have no PR to attach to a native milestone. + +## After v2.4.0: implemented, not yet version-released + +At baseline [`dc3d9bf`](https://github.com/bifrost0x/webssh/commit/dc3d9bf26f57cbeb440227afe13f9635c4d9f258), +13 additional PRs are merged. They cover workspace/tmux follow-ups, optional Warpgate, +paste/transcript correctness, connection/file usability and dependency maintenance. +See the [roadmap](../ROADMAP.md) and [release-readiness issue #248](https://github.com/bifrost0x/webssh/issues/248). + +Two important distinctions: + +- [#237](https://github.com/bifrost0x/webssh/issues/237) is closed and + [#238](https://github.com/bifrost0x/webssh/pull/238) is merged, but Warpgate is not part of + the v2.4.0 tag. The proposed next milestone must remain open for release validation. +- [#245](https://github.com/bifrost0x/webssh/issues/245) was resolved by the reporter's + Warpgate PROXY-protocol configuration. It is support evidence, not a shipped WebSSH fix. + Likewise, [#62](https://github.com/bifrost0x/webssh/issues/62) was converted to a database + proposal discussion. Neither is counted as implementation delivered by a release. + +## Lessons for future planning + +These are retrospective recommendations, not invented historical decisions: + +1. **Validate observable behavior.** #165 explains why an emitted event was insufficient + proof of scrolling. Acceptance should check what the user sees, including real devices + when automated browser coverage cannot reproduce their input stack. +2. **Treat integration and delivery separately.** A merged feature or closed issue can + precede a versioned release. Keep a separate release gate and record the exact candidate. +3. **Preserve compatibility explicitly.** #225 moved hardening into an opt-in overlay + after it threatened established deployments. Capacity, identity-provider and rollback + checks belong in the release record, not an implicit claim that green CI covers everything. +4. **Keep reasons and deferred work visible.** #20 explicitly deferred the large Paramiko + upgrade; #60 later included Paramiko 5 with broader runtime/security work. Record such + trade-offs instead of leaving a future reader to infer them from commit order. + +## Limits of this reconstruction + +No original release deadlines or complete private planning history were available. The +table summarizes documented purposes rather than claiming a pre-existing strategy. +Issue timelines show use of GitHub Projects, but this retrospective does not verify or +change the board's complete structure/status. Native milestone backfill is prepared in +the manifest and must be checked against the live GitHub milestone list before applying. diff --git a/docs/project-planning.md b/docs/project-planning.md new file mode 100644 index 00000000..eb9f4606 --- /dev/null +++ b/docs/project-planning.md @@ -0,0 +1,129 @@ +# Planning and Release Workflow + +Keep planning small enough to maintain. Use the roadmap for direction, milestones for +release grouping, issues for outcomes, and PRs for implementation evidence. + +## What belongs where + +| Surface | Question it answers | What to record | +|---|---|---| +| [Roadmap](../ROADMAP.md) | Where are we going and why? | Current release focus, next candidates and explicit non-commitments | +| [Milestone](https://github.com/bifrost0x/webssh/milestones) | Which release should deliver this? | Version, goal, acceptance, blockers and release link | +| Issue | Which problem/outcome needs work? | Benefit, reason for priority, acceptance criteria, dependencies and scope limits | +| Pull request | How was it implemented and verified? | Linked issue, implementation choices, tests, compatibility/security impact and rollout gaps | +| Release-readiness issue | Is the integrated work actually deliverable? | Exact candidate SHA, evidence, canary/upgrade results, publication and image verification | +| GitHub Release | What was actually shipped? | Published tag, user-facing changes, upgrade notes and delivery evidence | + +Existing GitHub Projects can remain a work view. They do not need to duplicate release +notes, and a board status must not be interpreted as proof of versioned publication. +This setup does not add or reorganize a Project. + +## A minimal working cycle + +1. **Capture the reason.** For substantial work, use an issue or a reviewed proposal. + Write the user problem, expected benefit and acceptance before implementation. + Small bug/dependency PRs do not require a duplicate issue. +2. **Select one active release scope.** Create a version milestone, such as `v2.5.0`, + with a short goal and a release-readiness issue. A proposed version is adjustable. + Do not set a due date unless the maintainer actually commits to it. +3. **Assign accepted work.** Attach the implementation issue and related PR to that + milestone. Link them with `Fixes #123` only when the PR really resolves the issue. + Use `Refs #123` for partial work. Keep ownership and existing useful labels explicit. +4. **Review and merge normally.** Required repository checks and human review rules + still apply. Record material trade-offs, validation environments and any deferred + acceptance. Planning never bypasses branch protection or security gates. +5. **Validate delivery.** Keep the release-readiness issue open after feature PRs merge. + Check the exact candidate, required CI, native image scans, relevant real-environment + acceptance and upgrade/recovery behavior. Link the evidence, not just a checkbox. +6. **Publish and verify.** Tag the reviewed candidate, publish release notes, and verify + the tag-triggered pipeline, versioned AMD64/ARM64 image and SBOM/provenance. Only then + close the readiness issue and milestone; move the outcome into completed history. + +Milestone progress is a count of closed work items, not effort completed or proof that +a version has shipped. A nearly complete milestone with a blocked release gate is still +not a published release. Issues and PRs can both represent the same outcome, so do not +interpret their combined count as distinct features delivered. + +## Example: optional Warpgate support + +[#237](https://github.com/bifrost0x/webssh/issues/237) states the user's gateway need. +[#238](https://github.com/bifrost0x/webssh/pull/238) implements selector usernames, +interactive authentication and a default-off administration gate. The request is closed +and the PR merged, but neither belongs to v2.4.0 because the tag predates their merge. + +The proposed v2.5.0 scope groups that implementation with the related workspace fixes. +[#248](https://github.com/bifrost0x/webssh/issues/248) remains open for exact-candidate +protocol checks, canary, upgrade/recovery, publication and image verification. This makes +the distinction between **implemented** and **shipped** visible without reopening the +resolved feature request or making a PR that repeats code already in `main`. + +## Record decisions and blockers + +Use a short dated comment on the relevant issue/PR: + +```text +Decision (YYYY-MM-DD): selected/deferred/changed . +Why: . +Trade-off: . +Acceptance: . +Blocker / next action: . +Evidence: . +``` + +Do not make an unresolved bug disappear by removing its milestone. If work moves, record +the old/new scope and reason. Security vulnerabilities still follow the private reporting +process in [SECURITY.md](../SECURITY.md), not a new public planning issue. + +## Release gate checklist + +Use the focused [v2.5.0 readiness checklist](https://github.com/bifrost0x/webssh/issues/248) +as the first example. Future checklists should include: + +- Confirmed scope/version and explicitly deferred items. +- Final candidate SHA and required CI/review evidence. +- Tests matching the changed risks; separate deployment-specific checks from automated CI. +- Upgrade, backup/restore and rollback results or explicit supported limitations. +- Current native AMD64/ARM64 scans and immutable source/image identity. +- Release notes, tag/release links and final versioned-image/attestation verification. + +Do not close a release gate before publication or infer a final-head test from an earlier +PR revision. An accepted operational limitation needs a maintainer decision; required +CI/security gates cannot be silently waived. No automation or automatic merge is added. + +## Maintaining the history + +The initial [release-history manifest](release-history.json) is a dated, reviewable +snapshot of ten published releases and the proposed next scope. It includes prepared +native milestone descriptions, 161 merged PR mappings and 24 verified issue links. +The candidate entry has no tag or publication date because it is not a release. + +For historical backfill: + +1. Read all existing native milestones before creating anything; reuse matching versions + and preserve their descriptions/dates unless the maintainer explicitly approves edits. +2. Use each release's first-tagged-inclusion mapping, not a merge date or a closed issue + timestamp. Do not attach unmerged/superseded PRs as delivered implementation. +3. Assign historical work and close only milestones for actually published releases. + Put the true publication date in the description. Do not invent historical due dates + or rewrite commit, issue, PR or release metadata to make the plan look older. +4. Keep the proposed next milestone open and include the release-readiness issue. + Verify every write, then update `native_milestone_backfill` in the snapshot with the + actual result/date and milestone numbers. Preserve unrelated existing assignments. + +For future releases, append evidence and a released entry when publication is verified; +retain historical tag membership. Update the roadmap's baseline/current section through +a normal documentation PR. Check links and keep reasons concise rather than copying +a commit-by-commit changelog. + +## Weekly review + +Read the latest release/tag comparison, recent merged/open PRs, open issues, the active +milestone and its readiness issue. Report: + +- Meaningful user/security/operational changes, not every commit. +- Implemented versus published outcomes. +- Actual blockers, owner/action and evidence gaps. +- At most three decisions or next actions; mark recommendations as recommendations. + +This allows a weekly status report to describe roadmap progress from public evidence +instead of guessing from the number of commits or closed tickets. diff --git a/docs/release-history.json b/docs/release-history.json new file mode 100644 index 00000000..08a406b7 --- /dev/null +++ b/docs/release-history.json @@ -0,0 +1,475 @@ +{ + "schema_version": 1, + "repository": "bifrost0x/webssh", + "reconstructed_on": "2026-10-03", + "baseline_commit": "dc3d9bf26f57cbeb440227afe13f9635c4d9f258", + "native_milestone_backfill": "prepared_not_applied", + "method": "First tagged release containing each merged PR's merge_commit_sha, with every compare page retrieved. The first release includes all prior verified PR merges. Issues require an explicit implementation link.", + "expected_merged_pr_count": 161, + "expected_implementation_linked_issue_count": 24, + "historical": [ + { + "title": "v1.0.0", + "state": "closed", + "goal": "First official self-hosted terminal and SFTP release", + "rationale_summary": "Package the existing multi-user terminal, tmux, SFTP and Docker capabilities as an official versioned baseline.", + "published_at": "2026-07-23T07:26:03Z", + "tag_commit": "9e73b60afd2573016652a8365ae5a7cd6d1f692b", + "previous_release": null, + "release_url": "https://github.com/bifrost0x/webssh/releases/tag/v1.0.0", + "compare_url": "https://github.com/bifrost0x/webssh/commits/v1.0.0", + "description": "Retrospective milestone reconstructed on 2026-10-03; not an original dated plan.\n\nGoal: First official self-hosted terminal and SFTP release.\nRationale summary (from linked release/PRs): Package the existing multi-user terminal, tmux, SFTP and Docker capabilities as an official versioned baseline.\n\nPublished: 2026-07-23. [Release](https://github.com/bifrost0x/webssh/releases/tag/v1.0.0) · [Git history](https://github.com/bifrost0x/webssh/commits/v1.0.0).\nTag commit: 9e73b60afd2573016652a8365ae5a7cd6d1f692b.\n\nAssign PRs by their first released merge commit, not merge/closure dates. 35 verified merged PRs. Key evidence: [#36](https://github.com/bifrost0x/webssh/pull/36), [#47](https://github.com/bifrost0x/webssh/pull/47), [#49](https://github.com/bifrost0x/webssh/pull/49), [#56](https://github.com/bifrost0x/webssh/pull/56).\n\nCreated/closed metadata reflects this backfill, not the original release date. Remaining deployment validation must not be inferred complete from historical closure.", + "pull_requests": [ + 1, + 3, + 4, + 5, + 7, + 9, + 11, + 12, + 13, + 14, + 15, + 16, + 17, + 18, + 20, + 33, + 34, + 35, + 36, + 37, + 38, + 39, + 41, + 42, + 43, + 44, + 45, + 46, + 47, + 49, + 51, + 52, + 53, + 55, + 56 + ], + "issues": [] + }, + { + "title": "v1.1.0", + "state": "closed", + "goal": "Modern runtime, identity and recoverable administration", + "rationale_summary": "The old runtime/dependency set constrained security updates; storage, host trust, transfers and recovery needed stronger failure boundaries.", + "published_at": "2026-08-03T14:44:42Z", + "tag_commit": "17d6ab8ff36e38b12cd615f4e5490d0d2ea87af3", + "previous_release": "v1.0.0", + "release_url": "https://github.com/bifrost0x/webssh/releases/tag/v1.1.0", + "compare_url": "https://github.com/bifrost0x/webssh/compare/v1.0.0...v1.1.0", + "description": "Retrospective milestone reconstructed on 2026-10-03; not an original dated plan.\n\nGoal: Modern runtime, identity and recoverable administration.\nRationale summary (from linked release/PRs): The old runtime/dependency set constrained security updates; storage, host trust, transfers and recovery needed stronger failure boundaries.\n\nPublished: 2026-08-03. [Release](https://github.com/bifrost0x/webssh/releases/tag/v1.1.0) · [Git history](https://github.com/bifrost0x/webssh/compare/v1.0.0...v1.1.0).\nTag commit: 17d6ab8ff36e38b12cd615f4e5490d0d2ea87af3.\n\nAssign PRs by their first released merge commit, not merge/closure dates. 10 verified merged PRs. Key evidence: [#60](https://github.com/bifrost0x/webssh/pull/60), [#71](https://github.com/bifrost0x/webssh/pull/71).\n\nCreated/closed metadata reflects this backfill, not the original release date. Remaining deployment validation must not be inferred complete from historical closure.", + "pull_requests": [ + 58, + 60, + 63, + 64, + 65, + 66, + 67, + 69, + 70, + 71 + ], + "issues": [] + }, + { + "title": "v1.2.0", + "state": "closed", + "goal": "Active-session server workspace", + "rationale_summary": "Put terminal, SFTP, diagnostics and navigation in the active server context rather than separate tools.", + "published_at": "2026-08-11T06:16:50Z", + "tag_commit": "055646858356274e9124d88fc42ee1c2a10256b1", + "previous_release": "v1.1.0", + "release_url": "https://github.com/bifrost0x/webssh/releases/tag/v1.2.0", + "compare_url": "https://github.com/bifrost0x/webssh/compare/v1.1.0...v1.2.0", + "description": "Retrospective milestone reconstructed on 2026-10-03; not an original dated plan.\n\nGoal: Active-session server workspace.\nRationale summary (from linked release/PRs): Put terminal, SFTP, diagnostics and navigation in the active server context rather than separate tools.\n\nPublished: 2026-08-11. [Release](https://github.com/bifrost0x/webssh/releases/tag/v1.2.0) · [Git history](https://github.com/bifrost0x/webssh/compare/v1.1.0...v1.2.0).\nTag commit: 055646858356274e9124d88fc42ee1c2a10256b1.\n\nAssign PRs by their first released merge commit, not merge/closure dates. 13 verified merged PRs. Key evidence: [#72](https://github.com/bifrost0x/webssh/pull/72), [#81](https://github.com/bifrost0x/webssh/pull/81), [#89](https://github.com/bifrost0x/webssh/pull/89), [#90](https://github.com/bifrost0x/webssh/pull/90).\n\nCreated/closed metadata reflects this backfill, not the original release date. Remaining deployment validation must not be inferred complete from historical closure.", + "pull_requests": [ + 72, + 78, + 79, + 80, + 81, + 82, + 83, + 84, + 85, + 86, + 88, + 89, + 90 + ], + "issues": [ + { + "number": 75, + "implemented_by": 81, + "evidence": "explicit closing reference in pull request body" + }, + { + "number": 76, + "implemented_by": 81, + "evidence": "explicit closing reference in pull request body" + }, + { + "number": 77, + "implemented_by": 81, + "evidence": "explicit closing reference in pull request body" + } + ] + }, + { + "title": "v1.3.0", + "state": "closed", + "goal": "Faster recurring administration", + "rationale_summary": "Make command insertion, saved-host ordering and stored-key replacement predictable without silently executing commands.", + "published_at": "2026-08-12T12:45:04Z", + "tag_commit": "7f5c68f3653ae0f910f5993b14dc6ae31285a767", + "previous_release": "v1.2.0", + "release_url": "https://github.com/bifrost0x/webssh/releases/tag/v1.3.0", + "compare_url": "https://github.com/bifrost0x/webssh/compare/v1.2.0...v1.3.0", + "description": "Retrospective milestone reconstructed on 2026-10-03; not an original dated plan.\n\nGoal: Faster recurring administration.\nRationale summary (from linked release/PRs): Make command insertion, saved-host ordering and stored-key replacement predictable without silently executing commands.\n\nPublished: 2026-08-12. [Release](https://github.com/bifrost0x/webssh/releases/tag/v1.3.0) · [Git history](https://github.com/bifrost0x/webssh/compare/v1.2.0...v1.3.0).\nTag commit: 7f5c68f3653ae0f910f5993b14dc6ae31285a767.\n\nAssign PRs by their first released merge commit, not merge/closure dates. 6 verified merged PRs. Key evidence: [#94](https://github.com/bifrost0x/webssh/pull/94), [#96](https://github.com/bifrost0x/webssh/pull/96), [#97](https://github.com/bifrost0x/webssh/pull/97), [#98](https://github.com/bifrost0x/webssh/pull/98).\n\nCreated/closed metadata reflects this backfill, not the original release date. Remaining deployment validation must not be inferred complete from historical closure.", + "pull_requests": [ + 91, + 94, + 95, + 96, + 97, + 98 + ], + "issues": [] + }, + { + "title": "v2.0.0", + "state": "closed", + "goal": "Authentication assurance and responsive workspace redesign", + "rationale_summary": "Protect sensitive operations with action/session/target-bound assurance while keeping contextual tools tied to the active SSH session.", + "published_at": "2026-08-21T18:06:45Z", + "tag_commit": "7c62c29a66c4755b166eb3949776c0d44a2b32d0", + "previous_release": "v1.3.0", + "release_url": "https://github.com/bifrost0x/webssh/releases/tag/v2.0.0", + "compare_url": "https://github.com/bifrost0x/webssh/compare/v1.3.0...v2.0.0", + "description": "Retrospective milestone reconstructed on 2026-10-03; not an original dated plan.\n\nGoal: Authentication assurance and responsive workspace redesign.\nRationale summary (from linked release/PRs): Protect sensitive operations with action/session/target-bound assurance while keeping contextual tools tied to the active SSH session.\n\nPublished: 2026-08-21. [Release](https://github.com/bifrost0x/webssh/releases/tag/v2.0.0) · [Git history](https://github.com/bifrost0x/webssh/compare/v1.3.0...v2.0.0).\nTag commit: 7c62c29a66c4755b166eb3949776c0d44a2b32d0.\n\nAssign PRs by their first released merge commit, not merge/closure dates. 16 verified merged PRs. Key evidence: [#106](https://github.com/bifrost0x/webssh/pull/106), [#124](https://github.com/bifrost0x/webssh/pull/124).\n\nCreated/closed metadata reflects this backfill, not the original release date. Remaining deployment validation must not be inferred complete from historical closure.", + "pull_requests": [ + 101, + 102, + 103, + 104, + 105, + 106, + 107, + 108, + 109, + 111, + 114, + 117, + 118, + 120, + 122, + 124 + ], + "issues": [] + }, + { + "title": "v2.1.0", + "state": "closed", + "goal": "Opt-in secure SMB file sources", + "rationale_summary": "Extend the file workspace beyond SFTP with explicit SMB security boundaries while fixing early 2.0 workflow regressions.", + "published_at": "2026-08-24T17:58:47Z", + "tag_commit": "81ecfedc3c550eb3970ef43238bacceb06cc2851", + "previous_release": "v2.0.0", + "release_url": "https://github.com/bifrost0x/webssh/releases/tag/v2.1.0", + "compare_url": "https://github.com/bifrost0x/webssh/compare/v2.0.0...v2.1.0", + "description": "Retrospective milestone reconstructed on 2026-10-03; not an original dated plan.\n\nGoal: Opt-in secure SMB file sources.\nRationale summary (from linked release/PRs): Extend the file workspace beyond SFTP with explicit SMB security boundaries while fixing early 2.0 workflow regressions.\n\nPublished: 2026-08-24. [Release](https://github.com/bifrost0x/webssh/releases/tag/v2.1.0) · [Git history](https://github.com/bifrost0x/webssh/compare/v2.0.0...v2.1.0).\nTag commit: 81ecfedc3c550eb3970ef43238bacceb06cc2851.\n\nAssign PRs by their first released merge commit, not merge/closure dates. 9 verified merged PRs. Key evidence: [#132](https://github.com/bifrost0x/webssh/pull/132), [#136](https://github.com/bifrost0x/webssh/pull/136), [#140](https://github.com/bifrost0x/webssh/pull/140).\n\nCreated/closed metadata reflects this backfill, not the original release date. Remaining deployment validation must not be inferred complete from historical closure.", + "pull_requests": [ + 126, + 127, + 128, + 129, + 132, + 136, + 137, + 139, + 140 + ], + "issues": [ + { + "number": 130, + "implemented_by": 132, + "evidence": "explicit closing reference in pull request body" + }, + { + "number": 131, + "implemented_by": 132, + "evidence": "explicit closing reference in pull request body" + }, + { + "number": 135, + "implemented_by": 136, + "evidence": "explicit closing reference in pull request body" + } + ] + }, + { + "title": "v2.2.0", + "state": "closed", + "goal": "Terminal-first mobile experience and managed identity", + "rationale_summary": "Respond to touch-device usability and management-workspace feedback while refining GitHub authentication and file/MFA safety.", + "published_at": "2026-08-30T12:14:56Z", + "tag_commit": "c9a2fd88fb4b203cdf19122c8f65c6418edf5ed6", + "previous_release": "v2.1.0", + "release_url": "https://github.com/bifrost0x/webssh/releases/tag/v2.2.0", + "compare_url": "https://github.com/bifrost0x/webssh/compare/v2.1.0...v2.2.0", + "description": "Retrospective milestone reconstructed on 2026-10-03; not an original dated plan.\n\nGoal: Terminal-first mobile experience and managed identity.\nRationale summary (from linked release/PRs): Respond to touch-device usability and management-workspace feedback while refining GitHub authentication and file/MFA safety.\n\nPublished: 2026-08-30. [Release](https://github.com/bifrost0x/webssh/releases/tag/v2.2.0) · [Git history](https://github.com/bifrost0x/webssh/compare/v2.1.0...v2.2.0).\nTag commit: c9a2fd88fb4b203cdf19122c8f65c6418edf5ed6.\n\nAssign PRs by their first released merge commit, not merge/closure dates. 15 verified merged PRs. Key evidence: [#147](https://github.com/bifrost0x/webssh/pull/147), [#158](https://github.com/bifrost0x/webssh/pull/158), [#161](https://github.com/bifrost0x/webssh/pull/161), [#164](https://github.com/bifrost0x/webssh/pull/164).\n\nCreated/closed metadata reflects this backfill, not the original release date. Remaining deployment validation must not be inferred complete from historical closure.", + "pull_requests": [ + 141, + 142, + 147, + 149, + 151, + 152, + 153, + 155, + 156, + 158, + 159, + 160, + 161, + 162, + 164 + ], + "issues": [ + { + "number": 143, + "implemented_by": 147, + "evidence": "explicit closing reference in pull request body" + }, + { + "number": 144, + "implemented_by": 147, + "evidence": "explicit closing reference in pull request body" + }, + { + "number": 145, + "implemented_by": 147, + "evidence": "explicit closing reference in pull request body" + }, + { + "number": 163, + "implemented_by": 164, + "evidence": "explicit closing reference in pull request body" + }, + { + "number": 146, + "implemented_by": 152, + "evidence": "maintainer comment in issue #146" + }, + { + "number": 154, + "implemented_by": 158, + "evidence": "connected pull request in issue #154 timeline" + } + ] + }, + { + "title": "v2.2.1", + "state": "closed", + "goal": "Focused mobile scrolling and session-tools correction", + "rationale_summary": "Synthetic wheel events did not move normal browser scrollback; verify actual viewport movement and expose session tools directly.", + "published_at": "2026-08-30T13:33:10Z", + "tag_commit": "d58ab2801c1ea1c18214fbf3908c8592559b6289", + "previous_release": "v2.2.0", + "release_url": "https://github.com/bifrost0x/webssh/releases/tag/v2.2.1", + "compare_url": "https://github.com/bifrost0x/webssh/compare/v2.2.0...v2.2.1", + "description": "Retrospective milestone reconstructed on 2026-10-03; not an original dated plan.\n\nGoal: Focused mobile scrolling and session-tools correction.\nRationale summary (from linked release/PRs): Synthetic wheel events did not move normal browser scrollback; verify actual viewport movement and expose session tools directly.\n\nPublished: 2026-08-30. [Release](https://github.com/bifrost0x/webssh/releases/tag/v2.2.1) · [Git history](https://github.com/bifrost0x/webssh/compare/v2.2.0...v2.2.1).\nTag commit: d58ab2801c1ea1c18214fbf3908c8592559b6289.\n\nAssign PRs by their first released merge commit, not merge/closure dates. 1 verified merged PRs. Key evidence: [#165](https://github.com/bifrost0x/webssh/pull/165).\n\nCreated/closed metadata reflects this backfill, not the original release date. Remaining deployment validation must not be inferred complete from historical closure.", + "pull_requests": [ + 165 + ], + "issues": [] + }, + { + "title": "v2.3.0", + "state": "closed", + "goal": "Everyday workflow reliability and stronger boundaries", + "rationale_summary": "Address mobile input, copying, transfers, notes and linking feedback while remediating validated security findings.", + "published_at": "2026-09-11T17:36:54Z", + "tag_commit": "2db70fad76223f75d62a15f596c271066d9623af", + "previous_release": "v2.2.1", + "release_url": "https://github.com/bifrost0x/webssh/releases/tag/v2.3.0", + "compare_url": "https://github.com/bifrost0x/webssh/compare/v2.2.1...v2.3.0", + "description": "Retrospective milestone reconstructed on 2026-10-03; not an original dated plan.\n\nGoal: Everyday workflow reliability and stronger boundaries.\nRationale summary (from linked release/PRs): Address mobile input, copying, transfers, notes and linking feedback while remediating validated security findings.\n\nPublished: 2026-09-11. [Release](https://github.com/bifrost0x/webssh/releases/tag/v2.3.0) · [Git history](https://github.com/bifrost0x/webssh/compare/v2.2.1...v2.3.0).\nTag commit: 2db70fad76223f75d62a15f596c271066d9623af.\n\nAssign PRs by their first released merge commit, not merge/closure dates. 27 verified merged PRs. Key evidence: [#185](https://github.com/bifrost0x/webssh/pull/185), [#198](https://github.com/bifrost0x/webssh/pull/198), [#202](https://github.com/bifrost0x/webssh/pull/202), [#209](https://github.com/bifrost0x/webssh/pull/209), [#211](https://github.com/bifrost0x/webssh/pull/211), [#212](https://github.com/bifrost0x/webssh/pull/212).\n\nCreated/closed metadata reflects this backfill, not the original release date. Remaining deployment validation must not be inferred complete from historical closure.", + "pull_requests": [ + 170, + 171, + 172, + 173, + 175, + 176, + 177, + 178, + 179, + 181, + 182, + 183, + 185, + 189, + 190, + 191, + 194, + 198, + 199, + 200, + 202, + 203, + 204, + 207, + 209, + 211, + 212 + ], + "issues": [ + { + "number": 180, + "implemented_by": 181, + "evidence": "explicit closing reference in pull request body" + }, + { + "number": 184, + "implemented_by": 185, + "evidence": "explicit closing reference in pull request body" + }, + { + "number": 187, + "implemented_by": 189, + "evidence": "explicit closing reference in pull request body" + }, + { + "number": 188, + "implemented_by": 189, + "evidence": "explicit closing reference in pull request body" + }, + { + "number": 192, + "implemented_by": 191, + "evidence": "explicit closing reference in pull request body" + }, + { + "number": 193, + "implemented_by": 194, + "evidence": "explicit closing reference in pull request body" + }, + { + "number": 196, + "implemented_by": 198, + "evidence": "explicit closing reference in pull request body" + }, + { + "number": 197, + "implemented_by": 198, + "evidence": "explicit closing reference in pull request body" + }, + { + "number": 208, + "implemented_by": 209, + "evidence": "explicit closing reference in pull request body" + }, + { + "number": 210, + "implemented_by": 211, + "evidence": "explicit closing reference in pull request body" + } + ] + }, + { + "title": "v2.4.0", + "state": "closed", + "goal": "Responsive multi-session recovery and verified releases", + "rationale_summary": "Prevent hidden-pane rendering from causing ACK evictions, synchronize files/terminal directories, and validate exact native images before promotion.", + "published_at": "2026-09-21T17:10:26Z", + "tag_commit": "570599896cf14411c82931d6e78f56eff8f5fa24", + "previous_release": "v2.3.0", + "release_url": "https://github.com/bifrost0x/webssh/releases/tag/v2.4.0", + "compare_url": "https://github.com/bifrost0x/webssh/compare/v2.3.0...v2.4.0", + "description": "Retrospective milestone reconstructed on 2026-10-03; not an original dated plan.\n\nGoal: Responsive multi-session recovery and verified releases.\nRationale summary (from linked release/PRs): Prevent hidden-pane rendering from causing ACK evictions, synchronize files/terminal directories, and validate exact native images before promotion.\n\nPublished: 2026-09-21. [Release](https://github.com/bifrost0x/webssh/releases/tag/v2.4.0) · [Git history](https://github.com/bifrost0x/webssh/compare/v2.3.0...v2.4.0).\nTag commit: 570599896cf14411c82931d6e78f56eff8f5fa24.\n\nAssign PRs by their first released merge commit, not merge/closure dates. 16 verified merged PRs. Key evidence: [#221](https://github.com/bifrost0x/webssh/pull/221), [#223](https://github.com/bifrost0x/webssh/pull/223), [#225](https://github.com/bifrost0x/webssh/pull/225), [#226](https://github.com/bifrost0x/webssh/pull/226), [#230](https://github.com/bifrost0x/webssh/pull/230).\n\nCreated/closed metadata reflects this backfill, not the original release date. Remaining deployment validation must not be inferred complete from historical closure.", + "pull_requests": [ + 215, + 216, + 217, + 218, + 219, + 220, + 221, + 222, + 223, + 224, + 225, + 226, + 227, + 228, + 229, + 230 + ], + "issues": [] + } + ], + "candidate": { + "title": "v2.5.0", + "state": "open", + "status": "proposed_not_released", + "goal": "Consolidate gateway support and workspace/terminal fixes into a verified release", + "baseline_commit": "dc3d9bf26f57cbeb440227afe13f9635c4d9f258", + "previous_release": "v2.4.0", + "compare_url": "https://github.com/bifrost0x/webssh/compare/v2.4.0...dc3d9bf26f57cbeb440227afe13f9635c4d9f258", + "description": "Proposed next release, no date commitment. Code after v2.4.0 is merged but not yet released under this version.\n\nGoal: consolidate optional Warpgate support, workspace/tmux continuity, paste/transcript correctness and reviewed dependency updates into a verified versioned release.\n\nRelease gate: [#248](https://github.com/bifrost0x/webssh/issues/248). Keep this issue open until exact-candidate validation, publication and versioned image/attestation verification are recorded.\n\nBaseline: dc3d9bf26f57cbeb440227afe13f9635c4d9f258 (2026-10-03), 13 merged PRs since v2.4.0. Native CI passed: https://github.com/bifrost0x/webssh/actions/runs/37064319620 . Scope/version remains adjustable by the maintainer.\n\nNo new features, release date or automatic merge commitment.", + "pull_requests": [ + 231, + 232, + 233, + 234, + 235, + 236, + 238, + 239, + 241, + 242, + 243, + 246, + 247 + ], + "issues": [ + { + "number": 240, + "implemented_by": 241, + "evidence": "explicit closing reference in pull request body" + }, + { + "number": 237, + "implemented_by": 238, + "evidence": "maintainer implementation comment in issue #237 and PR #238" + }, + { + "number": 248, + "evidence": "open release acceptance checklist" + } + ] + }, + "excluded_issues": [ + { + "number": 62, + "reason": "Converted to a discussion about optional PostgreSQL; not evidence of a shipped backend." + }, + { + "number": 245, + "reason": "Reporter resolved Warpgate PROXY-protocol configuration; no WebSSH code fix or release attribution." + } + ] +}