docs: add documentation for cross-namespace DevWorkspaceTemplate imports

[manweg]

What does this PR do?

Adds documentation for the controller.devfile.io/allow-import-from annotation,
which allows DevWorkspaceTemplates to be imported by DevWorkspaces in other namespaces.

Previously, this annotation was only documented in the source code
(pkg/library/flatten/flatten.go) but was not mentioned in the official documentation,
making it very difficult to discover. Without this documentation, users encounter the
misleading error Error processing devfile: plugin for component parent not found with
no indication of the solution.

What issues does this PR fix or reference?

Closes #1672

Is it tested? How?

This is a documentation-only change. The feature itself is already implemented and tested
in the codebase. The annotation has been verified to work as documented.

PR Checklist

• E2E tests pass (when PR is ready, comment /test v8-devworkspace-operator-e2e, v8-che-happy-path to trigger)
  • v8-devworkspace-operator-e2e: DevWorkspace e2e test
  • v8-che-happy-path: Happy path for verification integration with Che

Summary by CodeRabbit

• Documentation
  • Added guidance for configuring cross-namespace DevWorkspaceTemplate imports.
  • Documented supported annotation values, default behavior, and example YAML configurations for defining and referencing templates.

[openshift-ci]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: manweg
Once this PR has been reviewed and has the lgtm label, please assign dkwon17 for approval. For more information see the Code Review Process.

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]

Hi @manweg. Thanks for your PR.

I'm waiting for a devfile member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work.

Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

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.

[coderabbitai]

Warning

Review limit reached

@manweg, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 43 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1f63c5ff-643d-45cd-b64c-252395570c26

📥 Commits

Reviewing files that changed from the base of the PR and between 8d71e86 and b031484.

📒 Files selected for processing (1)

• docs/additional-configuration.adoc

📝 Walkthrough

Walkthrough

Adds documentation for configuring cross-namespace DevWorkspaceTemplate imports, including annotation semantics, defaults, supported values, and example manifests.

Changes

Cross-namespace DevWorkspaceTemplate imports

Layer / File(s)	Summary
Import configuration documentation docs/additional-configuration.adoc	Documents the controller.devfile.io/allow-import-from annotation, supported namespace values, default restrictions, and example template and workspace manifests.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Suggested reviewers: akurinnoy, btjd, dkwon17, ibuziuk, rohankanojia

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the documentation update for cross-namespace DevWorkspaceTemplate imports.
Linked Issues check	✅ Passed	The added docs cover the requested annotation, supported values, default behavior, and example usage in the official docs.
Out of Scope Changes check	✅ Passed	The change appears limited to the requested documentation update with no unrelated code or feature changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Warning

Review ran into problems

🔥 Problems

Git: Failed to clone repository. Please run the @coderabbitai full review command to re-trigger a full review. If the issue persists, set path_filters to include or exclude specific files.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[tolusha]

/che-ai-assistant ok-pr-readiness

Task completed.

[tolusha]

PR Readiness Assessment: PR #1673 — docs: add documentation for cross-namespace DevWorkspaceTemplate imports

Repository: devfile/devworkspace-operator
Linked Issue: #1672 — Document controller.devfile.io/allow-import-from annotation for cross-namespace DevWorkspaceTemplate imports

---

#	Criterion	Verdict	Notes
1	Problem Statement	PASS	Clear problem: undocumented annotation causes users to encounter misleading error messages with no discoverable solution
2	Reproduction Steps	PASS	Issue describes exact scenario: cross-namespace DevWorkspaceTemplate import without annotation results in Error processing devfile: plugin for component parent not found
3	Expected Behavior After Fix	PASS	Clear outcome: users can discover and use the annotation via official documentation to enable cross-namespace imports
4	Scope of Changes	PASS	Single documentation file changed, appropriate for a documentation-only PR that adds ~50 lines to docs/additional-configuration.adoc
5	Test Evidence	PASS	Appropriate for documentation-only change. PR states the feature is already implemented and tested; annotation has been verified to work as documented
6	Deployment & Verification Notes	PASS	Documentation itself is verifiable by reading the added content. The documented feature can be tested by applying the provided YAML examples

Overall: READY

---

What's Good

• Excellent problem statement: Both the PR and linked issue clearly explain the discoverability gap and the misleading error message users encounter
• Complete documentation: The added docs cover all use cases (wildcard *, specific namespace list, and default behavior)
• Concrete examples: Three YAML examples show how to define templates with the annotation and how to reference them from DevWorkspaces
• Appropriate scope: Documentation-only change with clear rationale for not requiring new tests
• Well-structured: New section is placed logically in the additional-configuration.adoc file
• Clear annotation semantics: Documents supported values, default behavior, and security implications of cross-namespace access

Verification Guidance

To verify this documentation change in a prerelease build:

1. Confirm the documentation is present in the deployed docs (check docs/additional-configuration.adoc contains the new "Configuring cross-namespace DevWorkspaceTemplate imports" section)
2. Optionally, validate the documented behavior by:
   • Creating a DevWorkspaceTemplate in namespace A with the annotation controller.devfile.io/allow-import-from: "namespace-b"
   • Creating a DevWorkspace in namespace B that references the template via parent.kubernetes
   • Confirming the workspace starts successfully without the plugin for component parent not found error

---

Assessment completed by ok-pr-readiness skill