Skip to content

docs(cloud): rename apps to projects across the portal documentation - #137

Merged
lukekim merged 1 commit into
spicehq:trunkfrom
claudespice:cloud/portal-projects-terminology
Aug 2, 2026
Merged

docs(cloud): rename apps to projects across the portal documentation#137
lukekim merged 1 commit into
spicehq:trunkfrom
claudespice:cloud/portal-projects-terminology

Conversation

@claudespice

Copy link
Copy Markdown
Contributor

Summary

The Cloud portal now calls the resource a Project everywhere a customer sees it — navigation, command menu, create flow, settings panels, danger-zone actions, public organization pages, and OAuth consent screens. The portal docs still said "App", so every page in the Portal section described labels that no longer exist in the product.

This renames the user-visible terminology across the Portal and Getting Started pages, and corrects several step-by-step flows that were already wrong against the current UI.

Deliberately not changed, because they are contracts rather than copy:

  • File paths and published URLs (/docs/portal/apps/...) — a URL rename needs redirects and is a separate decision.
  • OAuth scope strings apps:read / apps:write / apps:delete, which are unchanged and already documented as such in the Management API reference.
  • Historical changelog entries, which record what the product was called at the time.

Pages updated

Projects section

  • cloud/portal/apps/README.md — "Apps" → "Projects"; note on the rename and the legacy API paths.
  • cloud/portal/apps/delete.md — Delete flow: the danger-zone button is Delete project, the dialog is Delete Project, and confirmation requires typing <org-name>/<project-name> (the page previously said the project name alone) and clicking Delete. Replaced a link to a page that no longer exists with the Management APIs reference.
  • cloud/portal/apps/transfer.md — Transfer flow: Transfer project button, Transfer project page, <org-name>/<project-name> confirmation, Transfer & redeploy project submit. Added that transfer requires organization admin permissions and is blocked while a GitHub repository is connected. Repaired a broken organization link.
  • cloud/portal/apps/publish.md — Section is Project visibility; the control is Publish project / Make private with a confirmation dialog. Added the prerequisites: a connected public GitHub repository, and that viewers cannot change visibility.
  • cloud/portal/apps/api-keys.md — Key regeneration lives in Danger Zone, not under General, and the button reads Regenerate key.
  • cloud/portal/apps/tags.md — Save control is Save Tags followed by a confirmation; noted that reserved, platform-managed tag keys are hidden from the editor.
  • cloud/portal/apps/connect-github.md — Section is Connect Git Repository (Connected Git Repository once linked, with a Production Branch selector and Disconnect). Fixed duplicated step numbering.
  • cloud/portal/apps/secrets.md, runtime.md — terminology only.

Related Portal pages

  • cloud/portal/public-apps.md — "Public Apps" → "Public Projects"; publishing steps match the current control.
  • cloud/portal/app-spicepod/* — "App Spicepod" → "Project Spicepod"; terminology in deployment statuses and the Issues panel.
  • cloud/portal/spicerack.md — references to public projects.

Getting Started

  • cloud/getting-started/getting-started/portal-login-1.md — "Create a Spice app" → "Create a Spice project"; the create button is Create project.
  • cloud/getting-started/get-started/* — terminology in the remaining steps.

Navigation

  • cloud/SUMMARY.md — nav labels: Projects, Public Projects, Project Spicepod, Create a Spice project.

Notes for the reviewer

  • Follow-ups intentionally left out of scope: incidental "app" wording in cloud/portal/playground/, monitoring-and-request-logs.md, organizations.md, and organization-secrets.md; one reference in sdks/README.md; and a broken link to a removed Management API page in help/apis-and-sdks.md.
  • PR fix(docs): repair broken and cross-space docs links sitewide #127 touches cloud/portal/apps/delete.md, transfer.md, app-spicepod/README.md, and get-started/next-steps.md for link repairs. The overlaps are textual and small — this PR makes the same organization-link fix on transfer.md, and on delete.md it drops the dead #delete-app anchor rather than re-pointing to it.

Verification

  • Live-ness evidence: the rename is live in the production portal — the public organization page at https://spice.ai/spiceai renders "Projects", and the Management API's canonical /v1/projects routes are published in the API reference. All UI labels quoted above were read from the shipped implementation, not inferred.
  • Internal links resolve; no new pages added, so no SUMMARY.md additions needed beyond the relabelled entries
  • GitBook {% hint %} syntax used, not ::: admonitions
  • No private-repo references in branch name, commits, title, body, or content

Align the Cloud portal docs with the portal's Project terminology, and
correct the delete, transfer, publish, tags, and API key flows against
the current portal UI.
@lukekim lukekim self-assigned this Aug 2, 2026
@lukekim lukekim added the enhancement New feature or request label Aug 2, 2026
@lukekim
lukekim merged commit d279ae8 into spicehq:trunk Aug 2, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants