Add CONTRIBUTING.md and instructions for agents#191
Merged
stefanvanburen merged 1 commit intomainfrom Mar 27, 2026
Merged
Conversation
This adds a fairly straightforward CONTRIBUTING.md, based on [the one in connect-go][1]. It adds it at the repo root as opposed to .github/ as a stronger signal to agents. This also adds an AGENTS.md file with a light suggestion to agents to push back on creating PRs that modify public APIs without discussing in an issue first. We're approaching a stable API and want to carefully consider what we add at this point. We could carve out an "exception" for maintainers, but it's probably good for us maintainers to also consider future additions in an issue first anyway. Lastly, adds a CLAUDE.md that just `@` includes the AGENTS.md file (AFAIK, this is still the de-facto way to make this work with `claude`; we could also just symlink the files). With all of this, I suspect we can continue to refine these as we go, but this feels like a decent first step. Open to suggestions here, as this is all very new/fuzzy. Ref: https://agents.md/ [1]: https://github.com/connectrpc/connect-go/blob/main/.github/CONTRIBUTING.md Signed-off-by: Stefan VanBuren <[email protected]>
stefanvanburen
commented
Mar 26, 2026
| 1. Fork and clone the repository: | ||
|
|
||
| ```console | ||
| $ gh repo fork connectrpc/connect-python --clone |
Member
Author
There was a problem hiding this comment.
I assume most people use / are aware of the GitHub gh CLI; this simplifies these instructions, but of course we could also rewrite them to use raw git.
Collaborator
There was a problem hiding this comment.
Otherwise they're also likely familiar with using the raw git command anyways. I'm a fan of "soft tool recommendations" like this doc
stefanvanburen
commented
Mar 26, 2026
| ## Development Workflow | ||
|
|
||
| We use `just` as our task runner. | ||
| Run `uv run just --list` to see all available commands. |
Member
Author
There was a problem hiding this comment.
I don't want to be in the business of keeping a list of these commands in sync here as well.
anuraaga
approved these changes
Mar 27, 2026
| 1. Fork and clone the repository: | ||
|
|
||
| ```console | ||
| $ gh repo fork connectrpc/connect-python --clone |
Collaborator
There was a problem hiding this comment.
Otherwise they're also likely familiar with using the raw git command anyways. I'm a fan of "soft tool recommendations" like this doc
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This adds a fairly straightforward CONTRIBUTING.md, based on the one in connect-go. It adds it at the repo root as opposed to .github/ as a stronger signal to agents.
This also adds an AGENTS.md file with a light suggestion to agents to push back on creating PRs that modify public APIs without discussing in an issue first. We're approaching a stable API and want to carefully consider what we add at this point. We could carve out an "exception" for maintainers, but it's probably good for us maintainers to also consider future additions in an issue first anyway.
Lastly, adds a CLAUDE.md that just
@includes the AGENTS.md file (AFAIK, this is still the de-facto way to make this work withclaude; we could also just symlink the files).With all of this, I suspect we can continue to refine these as we go, but this feels like a decent first step. Open to suggestions here, as this is all very new/fuzzy.
Ref: https://agents.md/