Skip to content

Add change file style guide and agent skill for making a change file. - #38905

Open
SarahFrench wants to merge 6 commits into
mainfrom
add-change-file-styleguide-and-skill
Open

Add change file style guide and agent skill for making a change file.#38905
SarahFrench wants to merge 6 commits into
mainfrom
add-change-file-styleguide-and-skill

Conversation

@SarahFrench

@SarahFrench SarahFrench commented Jul 22, 2026

Copy link
Copy Markdown
Member

Happy for this to be closed if there are objections.

Related to #38904

This PR:

  • Adds a style guide document to the .changes folder where change files are created by contributors.
  • Links to that style guide from our contribution docs.
  • Adds a new write-change-file skill in .agents/skills that instructs an agent on how to prompt a user to create a meaningful change file that matches the style guide.
  • Adds a symlink at .bob/skill that points to .agents/skills removed as unnecessary.

Target Release

1.16.x

Rollback Plan

  • If a change needs to be reverted, we will roll out an update to the code within 7 days.

Changes to Security Controls

Are there any changes to security controls (access controls, encryption, logging) in this pull request? If so, explain.

CHANGELOG entry

  • This change is user-facing and I added a changelog entry.
  • This change is not user-facing.

@SarahFrench SarahFrench added the no-changelog-needed Add this to your PR if the change does not require a changelog entry label Jul 22, 2026
Comment thread .github/CONTRIBUTING.md
#### 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).

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

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.

@SarahFrench
SarahFrench marked this pull request as ready for review July 22, 2026 14:12
@SarahFrench
SarahFrench requested a review from a team as a code owner July 22, 2026 14:13
@SarahFrench

SarahFrench commented Jul 22, 2026

Copy link
Copy Markdown
Member Author

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.

@mildwonkey

Copy link
Copy Markdown
Contributor

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.

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

Labels

no-changelog-needed Add this to your PR if the change does not require a changelog entry

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants