Skip to content

docs: move README guidance to the official documentation website - #1406

Merged
Wassim Chegham (manekinekko) merged 6 commits into
mainfrom
manekinekko-documentation-migration
Oct 5, 2026
Merged

docs: move README guidance to the official documentation website#1406
Wassim Chegham (manekinekko) merged 6 commits into
mainfrom
manekinekko-documentation-migration

Conversation

@manekinekko

@manekinekko Wassim Chegham (manekinekko) commented Sep 18, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Summary

  • Replace the detailed root README with a short introduction and links to https://microsoft.github.io/scope/ for users and contributors.
  • Move local setup, first-evaluation instructions, development commands, contribution guidance, support, security, and licensing details into four new website pages.
  • Preserve the platform overview, run lifecycle, evaluation concepts, and repository references in the website, and update the sidebar, homepage, and contributor documentation to make the content discoverable.
  • Add two regression tests to apps/cli/src/utils/update-check.test.ts: a custom SCOPE_RELEASES_URL bypasses gh, and the lookup returns no version when no cli/v* release exists.

Merge with main

This branch originally also migrated the CLI installer, release workflow, and self-update to microsoft/scope. #1442 has since landed the canonical public installer and release workflow, so those changes now use main's implementation:

  • .github/workflows/publish-cli.yml, apps/cli/README.md, apps/cli/src/commands/update.ts, website/install-cli.sh, and docs/architecture/cli-distribution.md match main. The superseded website/install-cli.test.mjs was removed; scripts/install-cli.test.ts on main covers the installer.
  • The website install and access pages use the curl installer from main and still point to Local development when no CLI release is available.
  • Redesign Scope documentation with an interactive benchmark playground #1400 replaced the homepage cards with Home.astro, so the homepage now has a row of links to Local development, Contributing, and Support & security instead of two new cards.
  • The prompt-evaluation notes added to the old README on main (Add static prompt quality evaluations #1441) moved into the website development guide.
  • The Local development page sets SCOPE_API_URL explicitly because the CLI no longer has a default API URL.
  • The website contributor guide links to the community review policy in CONTRIBUTING.md (docs: define community contribution review and merge policy #1413).

Demo

N/A: documentation changes and unit tests only; no Portal or CLI behavior changes.

Testing

After merging main:

  • pnpm exec vitest run apps/cli/src/utils/update-check.test.ts apps/cli/src/commands/update.test.ts scripts/install-cli.test.ts: 25 tests passed.
  • cd website && pnpm test: all 7 plugin tests passed.
  • cd website && SITE=https://microsoft.github.io BASE_PATH=/scope pnpm build: passed with the public GitHub Pages base path. The new pages render and homepage links resolve under /scope/.

Before the merge:

  • Checked 9 affected rendered routes, all README documentation links, migrated content, and all 31 original README repository references.
  • git diff --check: passed.

Documentation and compatibility

New website pages:

These pages will be published when the website deployment includes this change. Existing introduction and getting-started pages, the website homepage/sidebar, and contributor instructions are updated as well.

Breaking changes, API/CLI compatibility impacts, and upgrade steps: None.

Checklist

  • If Portal features changed, keep CLI capabilities in sync. N/A: no Portal feature changes.
  • If Portal components changed, update their Storybook stories. N/A: no Portal component changes.
  • If database changes require a migration, include up() / down() and keep it CosmosDB-compatible. N/A: no database changes.
  • If dependencies changed, update the lockfile and regenerate NOTICE / NOTICE-REVIEW.txt with pnpm notice as needed. N/A: no dependency changes.

@manekinekko Wassim Chegham (manekinekko) added the type: documentation Documentation additions, corrections, and improvements. label Sep 18, 2026
@manekinekko
Wassim Chegham (manekinekko) marked this pull request as ready for review September 18, 2026 07:51
Copilot AI reviewed Sep 18, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Several promoted documentation paths retain obsolete repository references, and the first-run landing description is inaccurate.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Moves detailed README guidance into the official documentation website.

Changes:

  • Adds local development, contributor, development, support, and security guides.
  • Expands platform concepts and evaluation guidance.
  • Updates navigation and repository entry points.
File summaries
File Description
README.md Replaces detailed guidance with website links.
CONTRIBUTING.md Updates documentation contribution guidance.
website/README.md Documents the website’s new role.
website/astro.config.mjs Registers new sidebar pages.
website/src/content/docs/index.mdx Adds setup and contribution cards.
website/src/content/docs/getting-started/access.md Links local setup guidance.
website/src/content/docs/getting-started/first-run.md Updates first-run prerequisites.
website/src/content/docs/getting-started/local-development.md Adds comprehensive local setup instructions.
website/src/content/docs/introduction/concepts.md Adds evaluation building blocks.
website/src/content/docs/introduction/what-is-scope.md Expands architecture and interpretation guidance.
website/src/content/docs/resources/contributing.md Adds contribution and licensing guidance.
website/src/content/docs/resources/development.md Adds repository and development references.
website/src/content/docs/resources/support.md Adds support, security, and responsible-use guidance.
Review details
  • Files reviewed: 13/13 changed files
  • Comments generated: 3
  • Review effort level: Balanced

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread README.md Resolved
Comment thread website/README.md Resolved
Comment thread website/src/content/docs/getting-started/first-run.md Resolved
Copilot AI reviewed Sep 18, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

The migrated documentation is complete, internally consistent, discoverable, and aligned with repository behavior.

Review details
  • Files reviewed: 13/13 changed files
  • Comments generated: 0 new
  • Review effort level: Balanced

@github-actions

github-actions Bot commented Sep 18, 2026

Copy link
Copy Markdown

Test Results (Node.js 22)

test: Run #70

Tests 📝 Passed ✅ Failed ❌ Skipped ⏭️ Pending ⏳ Other ❓ Flaky 🍂 Duration ⏱️
2685 2685 0 0 0 0 0 57.2s

🎉 All tests passed!

Github Test Reporter

@github-actions

github-actions Bot commented Sep 18, 2026

Copy link
Copy Markdown

Test Results (Node.js 22)

test: Run #71

Tests 📝 Passed ✅ Failed ❌ Skipped ⏭️ Pending ⏳ Other ❓ Flaky 🍂 Duration ⏱️
2685 2685 0 0 0 0 0 1m16s

🎉 All tests passed!

Github Test Reporter

@github-actions

github-actions Bot commented Sep 18, 2026

Copy link
Copy Markdown

Test Results (Node.js 22)

test: Run #72

Tests 📝 Passed ✅ Failed ❌ Skipped ⏭️ Pending ⏳ Other ❓ Flaky 🍂 Duration ⏱️
2685 2685 0 0 0 0 0 1m13s

🎉 All tests passed!

Github Test Reporter

@manekinekko
Wassim Chegham (manekinekko) force-pushed the manekinekko-documentation-migration branch from 564f84f to 10d841f Compare September 24, 2026 14:57
@github-actions

github-actions Bot commented Sep 24, 2026

Copy link
Copy Markdown

Test Results (Node.js 22)

test: Run #93

Tests 📝 Passed ✅ Failed ❌ Skipped ⏭️ Pending ⏳ Other ❓ Flaky 🍂 Duration ⏱️
2998 2998 0 0 0 0 0 1m20s

🎉 All tests passed!

Github Test Reporter

@manekinekko
docs: move README guidance to the documentation website
24fc5fa 
Keep the README focused on introducing Scope and directing users and contributors to the official documentation. Move setup, development, contribution, support, and licensing details into navigable website pages.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@manekinekko
fix(cli): migrate installer and releases to microsoft/scope
f75c9df 
Align installation docs, release discovery, self-update downloads, and the publisher with the current repository. Build shared dependencies before publishing and cover installer transports and release lookups with regression tests.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@manekinekko
docs: align website contributor guidance with monorepo
b9996fc 
Use this microsoft/scope checkout as the documentation source of truth. Verify source-map links and clarify website, OpenAPI, and Pages workflow paths.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@manekinekko
docs: correct Portal landing view in first-run guide
1128ffe 
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@manekinekko
Wassim Chegham (manekinekko) force-pushed the manekinekko-documentation-migration branch from 10d841f to 1128ffe Compare September 24, 2026 15:28
@github-actions

github-actions Bot commented Sep 24, 2026

Copy link
Copy Markdown

Test Results (Node.js 22)

test: Run #96

Tests 📝 Passed ✅ Failed ❌ Skipped ⏭️ Pending ⏳ Other ❓ Flaky 🍂 Duration ⏱️
3005 3005 0 0 0 0 0 1m14s

🎉 All tests passed!

Github Test Reporter

@manekinekko
Merge origin/main into manekinekko-documentation-migration
0d285ce 
Resolve conflicts with the public CLI release work (#1442) and the
website redesign (#1400):

- Adopt main's canonical root installer, publish workflow, update
  command, and CLI distribution docs; drop the superseded website
  installer test while keeping the extra release-lookup test cases.
- Keep the slim README and port main's prompt-evaluation additions to
  the website development guide.
- Keep main's Home.astro landing and link local development,
  contributing, and support from it.
- Point local CLI usage at an explicit SCOPE_API_URL now that the CLI
  has no default API URL, and link the community review policy.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@manekinekko
Merge origin/main into manekinekko-documentation-migration
0770d35 
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@github-actions github-actions Bot added area: cli Scope command-line interface and terminal workflows. language: javascript Work involving JavaScript code, tooling, or dependencies. topic: testing Test coverage, test infrastructure, and validation quality. topic: ui Portal, visual presentation, layout, and interface components. labels Oct 1, 2026
@github-actions

github-actions Bot commented Oct 1, 2026

Copy link
Copy Markdown

Test Results (Node.js 22)

test: Run #166

Tests 📝 Passed ✅ Failed ❌ Skipped ⏭️ Pending ⏳ Other ❓ Flaky 🍂 Duration ⏱️
3179 3179 0 0 0 0 0 1m11s

🎉 All tests passed!

Github Test Reporter

Copilot AI reviewed Oct 1, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟢 Approval recommended

The documentation migration is coherent, discoverable, and consistent with the verified repository behavior.

Review effort: Balanced
Findings: None

Resolved since last review (3)

@manekinekko Wassim Chegham (manekinekko) added the area: website Scope documentation website (Astro) under website/. label Oct 1, 2026
duffney
Josh Duffney (duffney) reviewed Oct 5, 2026
View reviewed changes

@duffney Josh Duffney (duffney) left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@manekinekko
Wassim Chegham (manekinekko) merged commit e04df4b into main Oct 5, 2026
27 checks passed
@cedricvidal Cedric Vidal (cedricvidal) mentioned this pull request Oct 30, 2026
Draft
6 tasks done
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@duffney Josh Duffney (duffney) duffney left review comments
Copilot code review Copilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments

Assignees

@manekinekko Wassim Chegham (manekinekko)

Labels

area: cli Scope command-line interface and terminal workflows. area: website Scope documentation website (Astro) under website/. language: javascript Work involving JavaScript code, tooling, or dependencies. topic: testing Test coverage, test infrastructure, and validation quality. topic: ui Portal, visual presentation, layout, and interface components. type: documentation Documentation additions, corrections, and improvements.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@manekinekko @duffney