chore: enable agents to update public docs when making public changes - #129
Conversation
AGENTS.md said nothing about `docs/`, so an agent making a public-facing change to the plugin had no reason to touch the page that documents it. That happened in #128: the Codex install path landed with README and changeset updates but not the docs.slack.dev page, and the omission was caught in review rather than by the guidance. Adds a `## Public documentation` section stating that `docs/` is synced to docs.slack.dev from `main` by `slackapi/docs`, so the edit belongs in the same PR with no follow-up to open, and enumerating what counts as a public-facing change (install paths, the skills table, per-surface capability differences, anything that makes an existing statement wrong).
|
mwbrooks
added
docs
mwbrooks
changed the title
mwbrooks
changed the title
WilliamBergamin
left a comment
WilliamBergamin
left a comment
There was a problem hiding this comment.
Thanks for adding this 🚀
I have one none blocking concern about ending up with unreleased info in our documentation, left a comment about it
|
|
||
| ## Public documentation | ||
|
|
||
| `docs/` is published to [docs.slack.dev](https://docs.slack.dev/ai/slack-skills-plugin). The `slackapi/docs` repo syncs this directory from `main` (see its `sources.json`), so editing `docs/slack-skills-plugin.md` here is the whole job: there is no second PR to open, and the change goes live when it merges. |
There was a problem hiding this comment.
Do you think this will entice agents to edit the documentation along with changes?
From what I understand we want to merge docs changes along with the changeset PR so that we don't end up with unreleased information on the docs site 🤔
Maybe this is a none issue though
There was a problem hiding this comment.
@lukegalbraithrussell What's your take on this? When will the docs/ changes go live - on merge?
I agree with @WilliamBergamin - sometimes we'd like docs changes to go out immediately, but if they are documenting a change in a specific version, then we'd need it to go out when we do the release (which is when the changesets are merged).
There was a problem hiding this comment.
Maybe we should pull the docs from the most recent tag 🤔? this way we the docs and "code" are bundled together
There was a problem hiding this comment.
it's on merge. the problem with tying docs to release versions is you basically have to freeze the docs until release goes out. Example:
docs change 1: next-release only feature
docs change 2: typo fix
docs change 3: clarifying instructions
because the doc on main at change 1 is now tied to the release, changes 2 and 3 following are also waiting on the release. (it all also requires manually overriding the main listing on our side, and then reverting back, but i should figure out an easier solution for that)
Would it be possible to have the docs changes for a release be merged to a [release-version] branch instead of main, then that branch is merged to main on release?
There was a problem hiding this comment.
Good point @lukegalbraithrussell - there are 2 scenarios here:
- Immediate Updates: typos, minor improvements related to the current production experience
- Versioned Updates: updates dependent on unreleased features or changes
Right now, whatever is on main goes out immediately.
This seems to be true for all of our open source projects, so we should take a step back and find a solution that works across everything. Changesets and their chore: release PR might be a pattern we can leverage to protect the "Versioned Updates" scenario.
💬 I'll open a discussion around this topic.
Sounds like we'll ship this PR, since it's aligned with how docs work today.
3 participants
Summary
This pull request tells agents working in this repo that a public-facing change is not done until
docs/is updated, so the page developers actually read stops trailing the code by a PR.AGENTS.mdcovers commands, cross-skill references, skill descriptions, testing, CI, and releasing, but says nothing aboutdocs/. An agent adding a public capability therefore has no reason to opendocs/slack-skills-plugin.md, and the connection to docs.slack.dev is not discoverable from this repo at all: the sync lives inslackapi/docs, in asources.jsonentry pointing at this directory onmain.The new
## Public documentationsection states wheredocs/goes and that the edit belongs in the same PR, then enumerates what counts: a new or changed install command, a skill added/removed/renamed (and so the skills table), a capability that differs by surface, and anything that makes an existing statement on the page wrong. It closes by pointing atREADME.mdas the same obligation for people arriving via GitHub.Testing
No changeset:
AGENTS.mdis agent guidance, not a user-facing change, so it does not belong in the published CHANGELOG.Requirements
make testand the tests pass.