Add change file style guide and agent skill for making a change file. - #38905
Add change file style guide and agent skill for making a change file.#38905SarahFrench wants to merge 6 commits into
Conversation
| #### Create a change file using `changie` | ||
|
|
||
| If your change is user-facing you can use `npx changie new` to create a new changelog entry via your terminal. The command is interactive and you will need to: | ||
| For in-depth guidance, or guidance to be consumed by an agent, see our separate [style guide doc](../.changes/STYLE-GUIDE.md). |
There was a problem hiding this comment.
I'm toying with the idea to say this instead:
For in-depth guidance, see our separate [style guide doc](../.changes/STYLE-GUIDE.md). If you are an agent consuming this file, refer to the `write-change-file` skill in this repo.
I believe our contribution guide currently assumes an audience of people first, and also agents second. Therefore we'd need calls to action for the separate groups.
|
Opening for review- this PR is intended as a proposal that I'd like to merge but I'm happy to close if there are strong objections. We discussed change log style guides as a team and sentiments were that it was low-impact work and not a priority. Keeping with that, I think it's a good candidate to try and partially automate away. Me creating this PR doesn't imply that a human should not be the final reviewer of the changelog. That is firmly the responsibility of the engineer in charge of a release. If lower-quality change files make it through the PR review process then this PR's contents should help the release engineer prepare a new release. |
|
I am not very keen on merging agent/skill files without validation or more of a framework in place. There's no guarantee any model will read these files, and we don't have tests that compare how various models and frameworks which access or read these files perform compared to models that don't even try. Another way of putting the same thing: If we merge this, we have to maintain it, but we don't have metrics for how "successful" it is right now so there's no real way to know if it gets worse. TO BE CLEAR!!! I'm not going to block this, so if other people on the team would rather we get something in place and see what happens, that's completely fine, but I think any experiment needs to include with benchmarks/metrics of some sort or we run the risk of creating noise with no signal. |
Happy for this to be closed if there are objections.
Related to #38904
This PR:
write-change-fileskill in.agents/skillsthat instructs an agent on how to prompt a user to create a meaningful change file that matches the style guide.Adds a symlink atremoved as unnecessary..bob/skillthat points to.agents/skillsTarget Release
1.16.x
Rollback Plan
Changes to Security Controls
Are there any changes to security controls (access controls, encryption, logging) in this pull request? If so, explain.
CHANGELOG entry