Skip to content

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

Open
nickmisasi wants to merge 2 commits intov11.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 intov11.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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants