docs: add downstream-consumers reference for compat checks @W-24014386 - #355
docs: add downstream-consumers reference for compat checks @W-24014386#355nico-pappagianis wants to merge 9 commits into
Conversation
Document the repos that consume @salesforce/agents' public API (plugin-agent, vscode-agents, and the sf CLI transitively via plugin-agent) so code reviews can judge whether a change is breaking or backwards-incompatible, and where. Add ai-docs/downstream-consumers.md and link it from the CLAUDE.md convention hub.
nico-pappagianis
changed the title
nico-pappagianis
changed the title
| @@ -0,0 +1,51 @@ | |||
| # Downstream consumers | |||
There was a problem hiding this comment.
This already exists in the skill. Can we point the skill to this?
There was a problem hiding this comment.
Let me know if this is what you had in mind or prefer something else
|
This PR lacks any commits of the 'fix' or 'feat' type, and therefore will not trigger a release. To silence all further warnings, react to this warning comment (or any other) with the 👀 emoji. NOTE: If your repo uses squash commits, make sure to add the appropriate conventional commit prefix (e.g., 'fix:', 'feat:', 'chore:', etc) in the squash commit message. |
|
|
||
| For the public-API consumer contract — which repos are bound to the published API and how to | ||
| check a change for breaking / backwards-incompatible impact — see | ||
| [`ai-docs/downstream-consumers.md`](../../../ai-docs/downstream-consumers.md). |
There was a problem hiding this comment.
@setu4993 link to downstream consumers. Nice to have this table here still but we can delete it if we truly only want it in downstream-consumers.md. OK either way to me.
| `vscode-agents`) before publishing. Use `yarn link` for a live symlink while iterating: | ||
|
|
||
| ``` | ||
| yarn local:link /path/to/other/project |
There was a problem hiding this comment.
yarn local not a real command, not sure if this was supposed to be some local wrapper but the command doesn't exist.
| └─► afv-library (forcedotcom/afv-library) | ||
| Agent skills for vibe coding (developing/observing/testing-agentforce) | ||
| └─► sf-skills (forcedotcom/sf-skills) | ||
| Curated agent skills for Agentforce Vibes (works with all AI tools) |
There was a problem hiding this comment.
afv-library is now sf skills
2 participants
What
Docs-only changes that give code reviews (and sessions consuming a review) a consistent way to reason about this published library and how to test it, plus a cleanup of stale references in the dev-guide skill.
New references
ai-docs/downstream-consumers.md— the repos consuming@salesforce/agents' public API, so reviews can judge whether a change is breaking / backwards-incompatible and point at where:plugin-agentrather than importing the API.mainof each consumer, with a step-by-step for finding call sites a change would break.ai-docs/local-testing.md— how to test a change inside a consumer before publishing:yarn linkfor a live symlink (with the duplicate-@salesforce/corecaveat) andyarn packto QA the exact published artifact. Clarifies that thesfCLI is exercised transitively throughplugin-agent— you do not buildforcedotcom/cli.Hub + doc wiring
CLAUDE.mdlinks both new references from the convention hub.DEVELOPING.md
yarn local:link/unlink/installcommands (which never existed inpackage.json) with the realyarn link/yarn packflows, pointing atai-docs/local-testing.mdfor the full detail.dev-guide skill (
.claude/skills/sf-agents-dev-guide/SKILL.md)afv-library→sf-skills(renamed), dropped(private)onvscode-agents, removed three repos that no longer resolve (platformdx-shared-skills,afdx-skill-dev,afdx-skill-test).ai-docs/downstream-consumers.mdinstead of duplicating it.yarn local:*commands (now points atai-docs/local-testing.md), corrected the valid commit types to match@commitlint/config-conventional(removedimprovement) and the enforcement mechanism (commitlint, not commitizen), and removed a dead link to a nonexistentreferences/external-contacts.md.Why
@salesforce/agentsis published and consumers are pinned to released versions — they can't redeploy in lockstep. A change that passes this repo's own tests can still silently break a consumer bound to the old shape. These docs give reviewers a consistent way to catch that and to verify a change locally, and remove stale/incorrect guidance that had drifted from the actual repo.Notes
Docs only — no code or test changes.
@W-24014386