Skip to content

Sync agents submodule; exclude internal migration review docs from Sphinx#8945

Open
nickmisasi wants to merge 2 commits into
v11.7-documentationfrom
agents-docs-sync-v11.7
Open

Sync agents submodule; exclude internal migration review docs from Sphinx#8945
nickmisasi wants to merge 2 commits into
v11.7-documentationfrom
agents-docs-sync-v11.7

Conversation

@nickmisasi
Copy link
Copy Markdown
Contributor

Summary

  • Bump source/agents submodule to current mattermost-plugin-agents master (includes Agents v2 launch / upgrade documentation from the plugin repo).
  • Add agents/store/migrations/reviews/*.md to Sphinx exclude_patterns so plugin-internal schema migration review write-ups are not published to docs.mattermost.com or indexed as customer docs.

Test Plan

  • CI / docs build passes on this branch.

Follow-ups

See PR comment from @nickmisasi on orphaned / dead-link hygiene for migration-review content vs. upgrade-guide naming.

nickmisasi and others added 2 commits May 7, 2026 14:35
Advances mattermost-plugin-agents to 43738eed (docs: add Agents v2 launch documentation #709).

Co-authored-by: Cursor <cursoragent@cursor.com>
These files live in the plugin submodule for engineering review only; keep them off docs.mattermost.com and out of search.

Co-authored-by: Cursor <cursoragent@cursor.com>
@nickmisasi
Copy link
Copy Markdown
Contributor Author

Follow-up: “orphaned” migration-review vs. published upgrade docs

This PR deliberately does not publish the plugin-internal schema migration review Markdown under source/agents/store/migrations/reviews/ (Sphinx exclude_patterns). Customer-facing upgrade narrative lives in source/agents/docs/upgrading_to_2.0.md and related guides.

Please double-check link intent when you polish this area:

  1. Implicit slug / naming overlap (no Markdown links today, easy to confuse later)
    upgrading_to_2.0.md §4.1 lists migrations using identifiers such as 000005_create_user_agents_table, 000006_user_agent_bot_fields, 000007_create_conversations_table. Those strings match the basenames of excluded review files (000005_create_user_agents_table.md, etc.).

    • If we (or readers) ever assume “each row has a matching doc page,” those pages will not exist on docs.mattermost.com after this PR.
    • If you add deep links later, prefer one canonical customer page (e.g. upgrade guide section anchors) or GitHub links to the plugin repo / reviews directory—not docs.mattermost.com URLs under agents/store/migrations/reviews/.
  2. Repo-path callouts (not hyperlinks)
    §4.1 heading references the code path store/migrations/; §4.2 references server/legacy_bot_migration.go. These describe the source tree, not docs URLs—no change required unless we want explicit “view SQL on GitHub” links.

  3. Relative Markdown links inside the submodule
    upgrading_to_2.0.md ends with relative links to admin_guide.md and providers.md. managing_agents.md links to ../upgrading_to_2.0.md. When these pages are built in Sphinx, confirm each target is included in the site (toctree / includes) so those relatives don’t become dead links in HTML output.

  4. Quick audit (this branch)
    Grep did not find any […](…migrations/reviews…) or store/migrations/reviews Markdown links under source/agents/docs/. The gap is mainly expectation management and any future links you add.

Ping me if you want suggested replacement links (e.g. stable GitHub paths or a small “Schema migrations” subsection on the upgrade page) in a follow-up PR.

Comment thread source/conf.py
"agents/README.md",
"agents/interpluginclient/README.md",
# Plugin-internal schema migration reviews (submodule); not customer-facing docs
"agents/store/migrations/reviews/*.md",
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

@amyblais I added this so that the raw migration review files aren't shown in the docs site. I'm not sure how we usually handle these or where they go - but we have a few links to them in the upgrade notes

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

@nickmisasi I haven't updated this before, so I don't know what the usual process is. @esethna and @john-combs may know.

I've also removed the migrations from the v11.7 changelog as I didn't know they're not customer facing.

@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented May 7, 2026

Newest code from mattermost has been published to preview environment for Git SHA 0bfe88d

@amyblais amyblais requested review from Combs7th and esethna May 11, 2026 05:44
@amyblais amyblais added the 2: Editor Review Requires review by an editor label May 11, 2026
@amyblais amyblais added this to the v11.7.0 milestone May 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

2: Editor Review Requires review by an editor

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants