fix: use K8s resource name for backup and restore after workspace rename

[akurinnoy]

What does this PR do?

This PR fixes backup status fetching and restore conflict detection after workspace rename by adding a resourceName getter to the Workspace adapter. Additionally, decouples the user-typed workspace name from metadata.name during restore by auto-generating the resource name with a random suffix (matching the factory workspace creation pattern) and storing the user input as the display name label.

See packages/dashboard-frontend/docs/adr-001-auto-generate-resource-name-on-restore.md for the architectural decision record.

Screenshot/screencast of this PR

What issues does this PR fix or reference?

Fixes https://redhat.atlassian.net/browse/CRW-10477

Is it tested? How?

1. Deploy a cluster with backup enabled
2. Create a workspace from the dashboard
3. Navigate to the workspace details page (Overview tab)
4. Click "Edit Workspace Name" and rename the workspace
5. Click the "Backup" tab
6. Verify the backup status loads without errors (no 404 in the browser Network tab)
7. Confirm the backup-status API call uses the original K8s resource name, not the renamed display
   name
8. Navigate to the Workspaces list — verify the "Backup Status" column shows the correct status (e.g.
   "Never"), not an error
9. Wait for a backup to complete, then open the "Restore from Backup" page
10. Select the backup and restore it — verify the restored workspace appears with the user-typed
    display name and a suffixed metadata.name (visible via kubectl get devworkspaces)
11. Verify that restoring with a name matching the renamed workspace's old resource name no longer
    produces a false conflict error

Release Notes

Fixed backup status and restore failing after workspace rename. Restore now auto-generates the K8s resource name, consistent with workspace creation.

Docs PR

[che-bot]

Click here to review and test in web IDE:

[github-actions]

Docker image build succeeded: quay.io/eclipse/che-dashboard:pr-1565 (linux/amd64, linux/arm64)

kubectl patch command

kubectl patch -n eclipse-che "checluster/eclipse-che" --type=json -p="[{"op": "replace", "path": "/spec/components/dashboard/deployment", "value": {containers: [{image: "quay.io/eclipse/che-dashboard:pr-1565", name: che-dashboard}]}}]"

[github-actions]

Docker image build succeeded: quay.io/eclipse/che-dashboard:pr-1565 (linux/amd64, linux/arm64)

kubectl patch command

kubectl patch -n eclipse-che "checluster/eclipse-che" --type=json -p="[{"op": "replace", "path": "/spec/components/dashboard/deployment", "value": {containers: [{image: "quay.io/eclipse/che-dashboard:pr-1565", name: che-dashboard}]}}]"

[dkwon17]

To double check, was this doc meant to be committed to the repo? (I mean, should this file be merged to the main branch with this PR?)

[akurinnoy]

Yes, I committed it intentionally. The restore flow change is a non-trivial decision with trade-offs, so I'd like to keep ADRs for such changes in the repo, so the reasoning is next to the code itself. I believe this will help both humans and AI agents providing better code.

[akurinnoy]

We discussed the same matter with @rohanKanojia here: devfile/devworkspace-operator#1631 (review)
We agreed on having ADRs under the adr/ directory, in case of the dashboard - in the root of the package.

@olexii4 @svor Are you OK with this?

[svor]

@akurinnoy do I understand correctly that ADR files should be maintained and updated whenever the logic changes?

Also, I’m not sure whether we should reference the downstream issue here

[olexii4]

@akurinnoy Placing ADRs under packages/dashboard-frontend/adr/ is OK for me.

However, there is an important concern about treating ADRs as permanent, append-only artifacts.

ADR files like adr-001-auto-generate-resource-name-on-restore.md describe a decision that was correct at a point in time. When the underlying logic changes, the ADR can become stale or misleading. Unlike code, outdated ADRs don't produce compiler errors — they silently rot.

The risk: Without explicit rules for updating or retiring ADRs, the adr/ directory will accumulate documents that no longer reflect reality, which hurts rather than helps future contributors and AI agents.

What's needed before committing to this pattern:

• A policy for when an ADR should be updated vs. superseded (a new ADR that marks the old one as replaced).
• A policy for when an ADR should be removed (e.g., if the feature it describes is deleted entirely).
• Ideally, a lint or review checklist item: "Does this change affect an existing ADR?"

Without these rules, ADRs become archaeology rather than documentation.

Proposed First Step: Add a /docs Directory with a Project Snapshot

Before expanding the ADR convention further, a more immediately valuable step is to establish a top-level docs/ directory (or openspec/docs/) containing a snapshot description of the project — what it does, its key architectural boundaries, package structure, and major design decisions in effect today.

Why this matters:

• It gives human contributors and AI agents a fast-path to understanding the project without reading all the code.
• It saves time and LLM tokens on every AI-assisted task — agents can orient themselves from the snapshot rather than exploring the codebase from scratch each time.
• A single well-maintained snapshot is easier to keep accurate than a growing collection of individual ADRs.

The snapshot should be treated as a living document: updated when significant decisions change, not as a historical record. This is different from ADRs, which record the history of a decision.

[akurinnoy]

@svor thanks for the feedback

do I understand correctly that ADR files should be maintained and updated whenever the logic changes?

The standard ADR practice is append-only: old ADRs are not edited, instead you write a new one that supersedes the previous (with Status: Superseded by ADR-XXX). If the feature is removed entirely, you mark it Status: Deprecated. The idea is that ADRs are a decision log, not a living document. Even a deprecated ADR still has value - it explains why the approach was tried and why it was abandoned, so future contributors don't repeat the same mistakes.

I'm not sure whether we should reference the downstream issue here

Good point. I'll replace the Jira link with a reference to this PR.

[akurinnoy]

@olexii4 thanks for the thorough feedback

Regarding the ADR lifecycle - the standard ADR convention already covers this: ADRs are append-only, you don't edit old ones. If the logic changes, you write a new ADR that supersedes the previous one (Status: Superseded by ADR-XXX). If a feature is removed, you mark it Status: Deprecated. I can add a short README.md in the adr/ directory explaining this convention.

On the "silently rot" concern - ADRs don't describe current state, they describe why a decision was made at that point in time. A superseded or deprecated ADR is not stale, it's still doing its job: it explains why the approach was tried and why it was later changed or abandoned. This prevents future contributors from repeating the same mistakes.

Regarding the project snapshot in docs/ - interesting idea, but I think AGENTS.md in the repo root already serves this purpose. Happy to discuss expanding it, but that's a separate effort and shouldn't block shipping ADRs.

[github-actions]

Docker image build succeeded: quay.io/eclipse/che-dashboard:pr-1565 (linux/amd64, linux/arm64)

kubectl patch command

kubectl patch -n eclipse-che "checluster/eclipse-che" --type=json -p="[{"op": "replace", "path": "/spec/components/dashboard/deployment", "value": {containers: [{image: "quay.io/eclipse/che-dashboard:pr-1565", name: che-dashboard}]}}]"

[svor]

lgtm

[btjd]

I successfully verified this PR on a ROSA cluster running Eclipse Che 7.117.0 with global backups enabled. First, I confirmed the backup tracking fix by renaming a workspace from original-name to renamed-workspace; the dashboard correctly mapped the display name to the immutable Kubernetes ID and successfully displayed its backup status. Second, I verified the restore lifecycle by deploying a clone named restored-workspace. After sequentially stopping them to release storage locks, both instances independently achieved a clean Success backup state. Both the data mapping and resource-decoupling fixes are functional. LGTM

[svor]

/retest

[olexii4]

LGTM

[openshift-ci]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: akurinnoy, olexii4, svor

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[openshift-ci]

@akurinnoy: The following test failed, say /retest to rerun all failed tests or /retest-required to rerun all mandatory failed tests:

Test name	Commit	Details	Required	Rerun command
ci/prow/v19-dashboard-happy-path	b28ea63	link	true	/test v19-dashboard-happy-path

Full PR test history. Your PR dashboard.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.