docs: rc2 — adopt canonical attestix.* namespace across all docs + migration guide#92
Merged
Merged
Conversation
… guide + install bump Every Python snippet in the OSS docs now uses the canonical `attestix.*` namespace promoted in v0.4.0-rc.2 packaging refactor (#91). The pre-rc.2 flat top-level packages (`services/`, `auth/`, `storage/`, ...) still resolve via deprecation shims and emit a DeprecationWarning; they are scheduled for removal in v0.5.0, so the docs teach the canonical path going forward. Changes - website/content/docs/examples.mdx: 17 import statements rewritten to `from attestix.services... import ...` across all 11 example sections; added a leader callout linking to the new migration guide; install command surfaces both `pip install --pre attestix` (rc.2) and `pip install attestix` (stable 0.3.0). - website/content/docs/getting-started.mdx: install block now shows both the `--pre` (rc.2) and stable lines with a callout to the migration guide; the "Use as Python Library" snippet drops the `sys.path` shim and imports from `attestix.services.identity_service` directly. - website/content/docs/guides/base-l2-anchor.mdx: install block split into `--pre` rc.2 and stable; `BlockchainService` snippet now imports from `attestix.services.blockchain_service`. - website/content/docs/guides/integration-guide.mdx: the plain-Python wiring example imports all four services from `attestix.services.*`. - website/content/docs/guides/reputation.mdx: identity/reputation/delegation service imports rewritten to canonical namespace. - website/content/docs/reference/faq.mdx: "Can I use Attestix without MCP?" snippet rewritten to canonical namespace. - website/content/docs/guides/migration-v0.4.0-namespace.mdx: NEW guide covering why packaging changed (ICP funnel evaluation), what works in rc.2 (both paths, legacy warns), removal timeline (v0.5.0), full before/after substitution table, a one-liner ripgrep+sed migration script, deployment-string updates (`uvicorn api.main:app` -> `uvicorn attestix.api.main:app`), verification commands using `-W error::DeprecationWarning`, and `pip install --pre attestix==0.4.0rc2` pin instructions. Linked from CHANGELOG.md rc.2 entry plus the touched docs. - website/content/docs/guides/meta.json: register the new migration guide in the Fumadocs sidebar. Validation - `npx next build` in `website/`: 60/60 static pages, including `/docs/guides/migration-v0.4.0-namespace` (built artifact verified at `website/out/docs/guides/migration-v0.4.0-namespace.html`). - Post-edit grep for legacy patterns across `website` + `README.md` (excluding the migration guide which intentionally quotes both forms): zero literal `from <flat>.X import` Python imports remain in any code block. Remaining hits are narrative text (callouts explaining the deprecation shim) plus already-canonical `attestix.api.main:app` references in README. - Smoke test in throwaway venv with `pip install --pre attestix==0.4.0rc2`: python -c "from attestix.services.identity_service import IdentityService; print('canonical ok:', IdentityService.__module__)" -> canonical ok: attestix.services.identity_service python -W error::DeprecationWarning -c "from attestix.services.identity_service import IdentityService" -> exits 0 (no warning, no error) python -W error::DeprecationWarning -c "from services.identity_service import IdentityService" -> raises DeprecationWarning: "Importing from the top-level `services` package is deprecated and will be removed in Attestix v0.5.0. Update your imports to `from attestix.services...` (canonical namespace)." No functional code changed; this PR is documentation-only and ships alongside the rc.2 packaging fix already on `main`.
|
Note
|
| Layer / File(s) | Summary |
|---|---|
Getting Started and Examples website/content/docs/getting-started.mdx, website/content/docs/examples.mdx |
Installation guidance updated to recommend pip install --pre attestix for v0.4.0-rc.2 canonical namespace. All code examples across both documents switched from legacy services.* imports to attestix.services.*, with intro text noting the deprecation timeline and removal in v0.5.0. |
Feature-Specific Guide Updates website/content/docs/guides/base-l2-anchor.mdx, website/content/docs/guides/integration-guide.mdx, website/content/docs/guides/reputation.mdx, website/content/docs/reference/faq.mdx |
Import paths in individual guides updated to canonical namespace. Prerequisites sections note v0.4.0-rc.2 pre-release install and legacy compatibility. Documented feature workflows remain unchanged. |
Comprehensive Migration Guide website/content/docs/guides/migration-v0.4.0-namespace.mdx |
New guide documenting v0.4.0-rc.2 migration with: compatibility explanation for v0.4.0-rc.2 (legacy still works via deprecation shims), removal timeline (v0.5.0), mechanical substitution table, automated ripgrep/sed workflow with dry-run option, deployment string updates (uvicorn, gunicorn, Docker, systemd, MCP), verification using -W error::DeprecationWarning, and pip pinning commands. |
Documentation Navigation website/content/docs/guides/meta.json |
Added two new guide pages (base-l2-anchor and migration-v0.4.0-namespace) to site navigation structure. |
🎯 2 (Simple) | ⏱️ ~10 minutes
🚥 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 and concisely describes the main change: adopting the canonical attestix.* namespace across all documentation and adding a migration guide for v0.4.0-rc.2. |
| Docstring Coverage | ✅ Passed | No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. |
| Linked Issues check | ✅ Passed | Check skipped because no linked issues were found for this pull request. |
| Out of Scope Changes check | ✅ Passed | Check skipped because no linked issues were found for this pull request. |
✏️ Tip: You can configure your own custom pre-merge checks in the settings.
✨ Finishing Touches
🧪 Generate unit tests (beta)
- Create PR with unit tests
- Commit unit tests in branch
docs/rc2-canonical-imports
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.
Comment @coderabbitai help to get the list of available commands and usage tips.
Deploying attestix with
|
| Latest commit: |
e9e01a1
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://9d8211b5.attestix.pages.dev |
| Branch Preview URL: | https://docs-rc2-canonical-imports.attestix.pages.dev |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@website/content/docs/examples.mdx`:
- Around line 8-12: The documentation incorrectly claims "All examples work
standalone after `pip install attestix` (stable 0.3.0)" while the snippets use
the new `attestix.*` namespace introduced in v0.4.0-rc.2; update the wording to
state that examples require the pre-release `v0.4.0-rc.2` (or later) to use
`attestix.*`, and note that stable `0.3.0` only supports the legacy flat imports
(or include both import examples). Specifically, change the sentence referencing
`pip install --pre attestix (v0.4.0-rc.2 release candidate)` and `pip install
attestix (stable 0.3.0)` to clearly indicate that the canonical `attestix.*`
imports require the rc2+ pre-release, and optionally add a short note pointing
to the migration guide for legacy `from services... import` usage.
In `@website/content/docs/guides/migration-v0.4.0-namespace.mdx`:
- Around line 87-90: The one-liner only matches "from X" imports and misses
plain "import X" forms; update the ripgrep pattern to find both forms (e.g.
search for '\b(from|import) (services|auth|storage|...)\b') and change the sed
substitution to handle both captures so "from services..." becomes "from
attestix.services..." and "import services" (including "import services as s")
becomes "import attestix.services" (preserving any alias or trailing text). Keep
the same group of module names and use alternation in sed (e.g. match
'^(from|import) (services|...)(\.|\b)' and replace with '\1 attestix.\2\3',
preserving the leading keyword and any suffix).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 18442b2a-8f55-44a7-a306-7b3d093dbbbb
📒 Files selected for processing (8)
website/content/docs/examples.mdxwebsite/content/docs/getting-started.mdxwebsite/content/docs/guides/base-l2-anchor.mdxwebsite/content/docs/guides/integration-guide.mdxwebsite/content/docs/guides/meta.jsonwebsite/content/docs/guides/migration-v0.4.0-namespace.mdxwebsite/content/docs/guides/reputation.mdxwebsite/content/docs/reference/faq.mdx
Comment on lines
+8
to
+12
| Runnable examples for every Attestix module. All examples work standalone after `pip install --pre attestix` (v0.4.0-rc.2 release candidate) or `pip install attestix` (stable 0.3.0). | ||
|
|
||
| v0.4.0-rc.2 ships the canonical `attestix.*` namespace shown below. The pre-rc.2 | ||
| flat layout (`from services... import`) still works as a deprecation shim but is | ||
| scheduled for removal in v0.5.0. See the [namespace migration guide](/docs/guides/migration-v0.4.0-namespace). |
There was a problem hiding this comment.
Fix version-compatibility claim for runnable snippets.
The text says all examples run on stable 0.3.0, but the snippets below use attestix.* imports (rc2+ canonical path). That mismatch will break copy/paste for stable users.
Suggested wording fix
-Runnable examples for every Attestix module. All examples work standalone after `pip install --pre attestix` (v0.4.0-rc.2 release candidate) or `pip install attestix` (stable 0.3.0).
+Runnable examples for every Attestix module. These snippets target the canonical `attestix.*` namespace and run after `pip install --pre attestix` (v0.4.0-rc.2 release candidate, and later).
-v0.4.0-rc.2 ships the canonical `attestix.*` namespace shown below. The pre-rc.2
-flat layout (`from services... import`) still works as a deprecation shim but is
-scheduled for removal in v0.5.0. See the [namespace migration guide](/docs/guides/migration-v0.4.0-namespace).
+If you are on stable `0.3.0` (`pip install attestix`), use the legacy flat imports (`from services...`) or migrate using the [namespace migration guide](/docs/guides/migration-v0.4.0-namespace).📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| Runnable examples for every Attestix module. All examples work standalone after `pip install --pre attestix` (v0.4.0-rc.2 release candidate) or `pip install attestix` (stable 0.3.0). | |
| v0.4.0-rc.2 ships the canonical `attestix.*` namespace shown below. The pre-rc.2 | |
| flat layout (`from services... import`) still works as a deprecation shim but is | |
| scheduled for removal in v0.5.0. See the [namespace migration guide](/docs/guides/migration-v0.4.0-namespace). | |
| Runnable examples for every Attestix module. These snippets target the canonical `attestix.*` namespace and run after `pip install --pre attestix` (v0.4.0-rc.2 release candidate, and later). | |
| If you are on stable `0.3.0` (`pip install attestix`), use the legacy flat imports (`from services...`) or migrate using the [namespace migration guide](/docs/guides/migration-v0.4.0-namespace). |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@website/content/docs/examples.mdx` around lines 8 - 12, The documentation
incorrectly claims "All examples work standalone after `pip install attestix`
(stable 0.3.0)" while the snippets use the new `attestix.*` namespace introduced
in v0.4.0-rc.2; update the wording to state that examples require the
pre-release `v0.4.0-rc.2` (or later) to use `attestix.*`, and note that stable
`0.3.0` only supports the legacy flat imports (or include both import examples).
Specifically, change the sentence referencing `pip install --pre attestix
(v0.4.0-rc.2 release candidate)` and `pip install attestix (stable 0.3.0)` to
clearly indicate that the canonical `attestix.*` imports require the rc2+
pre-release, and optionally add a short note pointing to the migration guide for
legacy `from services... import` usage.
Comment on lines
+87
to
+90
| ```bash | ||
| rg -l --type py 'from (services|auth|storage|signing|audit|tenancy|idempotency|blockchain|tools|api|config|errors)\b' \ | ||
| | xargs sed -i -E 's/^from (services|auth|storage|signing|audit|tenancy|idempotency|blockchain|tools|api|config|errors)(\.|\b)/from attestix.\1\2/' | ||
| ``` |
There was a problem hiding this comment.
Broaden the one-liner to cover import services-style legacy imports too.
The command currently rewrites only from ... imports, but your mapping table also includes plain import services forms. As written, migration can silently miss those files.
Suggested command update
-rg -l --type py 'from (services|auth|storage|signing|audit|tenancy|idempotency|blockchain|tools|api|config|errors)\b' \
- | xargs sed -i -E 's/^from (services|auth|storage|signing|audit|tenancy|idempotency|blockchain|tools|api|config|errors)(\.|\b)/from attestix.\1\2/'
+rg -l --type py '^(from|import) (services|auth|storage|signing|audit|tenancy|idempotency|blockchain|tools|api|config|errors)\b' \
+ | xargs sed -i -E \
+ -e 's/^from (services|auth|storage|signing|audit|tenancy|idempotency|blockchain|tools|api|config|errors)(\.|\b)/from attestix.\1\2/' \
+ -e 's/^import (services|auth|storage|signing|audit|tenancy|idempotency|blockchain|tools|api|config|errors)(\.|\b)/import attestix.\1\2/'📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ```bash | |
| rg -l --type py 'from (services|auth|storage|signing|audit|tenancy|idempotency|blockchain|tools|api|config|errors)\b' \ | |
| | xargs sed -i -E 's/^from (services|auth|storage|signing|audit|tenancy|idempotency|blockchain|tools|api|config|errors)(\.|\b)/from attestix.\1\2/' | |
| ``` |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@website/content/docs/guides/migration-v0.4.0-namespace.mdx` around lines 87 -
90, The one-liner only matches "from X" imports and misses plain "import X"
forms; update the ripgrep pattern to find both forms (e.g. search for
'\b(from|import) (services|auth|storage|...)\b') and change the sed substitution
to handle both captures so "from services..." becomes "from
attestix.services..." and "import services" (including "import services as s")
becomes "import attestix.services" (preserving any alias or trailing text). Keep
the same group of module names and use alternation in sed (e.g. match
'^(from|import) (services|...)(\.|\b)' and replace with '\1 attestix.\2\3',
preserving the leading keyword and any suffix).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Doc-only backfill for the v0.4.0-rc.2 packaging refactor (#91). Every Python snippet in the OSS docs now teaches the canonical
attestix.*namespace instead of the pre-rc.2 flat top-level imports (from services... import,from auth... import, etc.). Adds a dedicated migration guide for users upgrading from 0.3.0 / rc.1.from <flat>.X import YPython snippets in the website docs tofrom attestix.<flat>.X import Y.examples,getting-started,base-l2-anchor) to surface bothpip install --pre attestix(rc.2) andpip install attestix(stable 0.3.0).website/content/docs/guides/migration-v0.4.0-namespace.mdxcovering the why (ICP funnel evaluation finding), what works today (both paths; legacy warns), removal timeline (v0.5.0), the full before/after substitution table, a one-linerripgrep + sedscript for bulk migration, deployment-string updates (uvicorn api.main:app→uvicorn attestix.api.main:app, plusgunicorn/Dockerfile/systemd/ MCP forms), and verification commands using-W error::DeprecationWarning.website/content/docs/guides/meta.json.No functional code change. The rc.2 wheel already ships the canonical namespace with deprecation shims for the legacy paths; this PR only updates what the docs teach.
Files changed
8 files (7 modified, 1 new):
website/content/docs/examples.mdxwebsite/content/docs/getting-started.mdxwebsite/content/docs/guides/base-l2-anchor.mdxwebsite/content/docs/guides/integration-guide.mdxwebsite/content/docs/guides/meta.jsonwebsite/content/docs/guides/reputation.mdxwebsite/content/docs/reference/faq.mdxwebsite/content/docs/guides/migration-v0.4.0-namespace.mdx(new)The README is already canonical (touched in #91) so no edits there.
Validation
Website build
npx next buildinwebsite/: 60/60 static pages, including the new/docs/guides/migration-v0.4.0-namespaceroute. Built artifact verified atwebsite/out/docs/guides/migration-v0.4.0-namespace.html.Grep for residual legacy imports
After edits, the post-edit grep across
website/+README.md, excluding the migration guide which intentionally quotes both forms:Zero literal legacy
from <flat>.X importPython imports remain in any code block.rc.2 smoke test (throwaway venv)
The canonical path passes under strict warnings; the legacy path raises with the exact replacement guidance the migration guide documents.
Test plan
/docs/getting-started,/docs/examples,/docs/guides/integration-guide,/docs/guides/reputation,/docs/guides/base-l2-anchor,/docs/reference/faqall showfrom attestix.services... import ...in code blocks./docs/getting-startedmentions bothpip install --pre attestixandpip install attestix.Summary by CodeRabbit