Skip to content

Commit 65cdb27

Browse files
nearlyforgetnearlyforget
authored
Merge pull request #4 from nearlyforget/community-health
docs: add contributing, governance, code of conduct, and pr template
2 parents 7a96a9c + 7867d26 commit 65cdb27

5 files changed

Lines changed: 519 additions & 0 deletions

File tree

‎.github/pull_request_template.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Description
2+
3+
<!-- Please provide a brief description of the changes in this pull request. -->
4+
5+
## Category (Required)
6+
7+
*Please select one or more categories that apply to this change.*
8+
9+
- [ ] **Core Protocol**: Changes to the base communication layer, global context, or breaking refactors. (Requires Technical Council approval)
10+
- [ ] **Governance/Contributing**: Updates to GOVERNANCE.md, CONTRIBUTING.md, or CODEOWNERS. (Requires Governance Council approval)
11+
- [ ] **Capability**: New schemas (Discovery, Cart, etc.) or extensions. (Requires Maintainer approval)
12+
- [ ] **Documentation**: Updates to README, or documentations regarding schema or capabilities. (Requires Maintainer approval)
13+
- [ ] **Infrastructure**: CI/CD, Linters, or build scripts. (Requires DevOps Maintainer approval)
14+
- [ ] **Maintenance**: Version bumps, lockfile updates, or minor bug fixes. (Requires DevOps Maintainer approval)
15+
- [ ] **SDK**: Language-specific SDK updates and releases. (Requires DevOps Maintainer approval)
16+
- [ ] **Samples / Conformance**: Maintaining samples and the conformance suite. (Requires Maintainer approval)
17+
- [ ] **UCP Schema**: Changes to the `ucp-schema` tool (resolver, linter, validator). (Requires Maintainer approval)
18+
- [ ] **Community Health (.github)**: Updates to templates, workflows, or org-level configs. (Requires DevOps Maintainer approval)
19+
20+
21+
## Related Issues
22+
23+
<!-- Link to any related issues here. e.g., "Fixes #123" -->
24+
25+
## Checklist
26+
27+
- [ ] I have followed the [Contributing Guide](https://github.com/agentic-commerce/ucp/blob/main/CONTRIBUTING.md).
28+
- [ ] I have updated the documentation (if applicable).
29+
- [ ] My changes pass all local linting and formatting checks.
30+
- [ ] (For Core/Capability) I have included/updated the relevant JSON schemas.
31+
- [ ] I have regenerated Python Pydantic models by running generate_models.sh under python_sdk.
32+
33+
## Screenshots / Logs (if applicable)
34+
35+
<!-- If applicable, add screenshots or log output to help explain your changes. -->

‎CODE_OF_CONDUCT.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
<!--
2+
Copyright 2026 UCP Authors
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
-->
16+
17+
# Code of Conduct
18+
19+
## Our Pledge
20+
21+
In the interest of fostering an open and welcoming environment, we as
22+
contributors and maintainers pledge to making participation in our project and
23+
our community a harassment-free experience for everyone, regardless of age, body
24+
size, disability, ethnicity, gender identity and expression, level of
25+
experience, education, socio-economic status, nationality, personal appearance,
26+
race, religion, or sexual identity and orientation.
27+
28+
## Our Standards
29+
30+
Examples of behavior that contributes to creating a positive environment
31+
include:
32+
33+
* Using welcoming and inclusive language
34+
* Being respectful of differing viewpoints and experiences
35+
* Gracefully accepting constructive criticism
36+
* Focusing on what is best for the community
37+
* Showing empathy towards other community members
38+
39+
Examples of unacceptable behavior by participants include:
40+
41+
* The use of sexualized language or imagery and unwelcome sexual attention or
42+
advances
43+
* Trolling, insulting/derogatory comments, and personal or political attacks
44+
* Public or private harassment
45+
* Publishing others' private information, such as a physical or electronic
46+
address, without explicit permission
47+
* Disrespecting the community's time by sending spam or other unsolicited
48+
commercial messages
49+
* Other conduct which could reasonably be considered inappropriate in a
50+
professional setting
51+
52+
## Our Responsibilities
53+
54+
Project maintainers are responsible for clarifying the standards of acceptable
55+
behavior and are expected to take appropriate and fair corrective action in
56+
response to any instances of unacceptable behavior.
57+
58+
Project maintainers have the right and responsibility to remove, edit, or reject
59+
comments, commits, code, wiki edits, issues, and other contributions that are
60+
not aligned to this Code of Conduct, or to ban temporarily or permanently any
61+
contributor for other behaviors that they deem inappropriate, threatening,
62+
offensive, or harmful.
63+
64+
## Scope
65+
66+
This Code of Conduct applies both within project spaces and in public spaces
67+
when an individual is representing the project or its community. Examples of
68+
representing a project or community include using an official project e-mail
69+
address, posting via an official social media account, or acting as an appointed
70+
representative at an online or offline event. Representation of a project may be
71+
further defined and clarified by project maintainers.
72+
73+
This Code of Conduct also applies outside the project spaces when the Project
74+
Steward has a reasonable belief that an individual's behavior may have a
75+
negative impact on the project or its community.
76+
77+
## Conflict Resolution
78+
79+
We do not believe that all conflict is bad; healthy debate and disagreement
80+
often yield positive results. However, it is never okay to be disrespectful or
81+
to engage in behavior that violates the project’s code of conduct.
82+
83+
If you see someone violating the code of conduct, you are encouraged to address
84+
the behavior directly with those involved. Many issues can be resolved quickly
85+
and easily, and this gives people more control over the outcome of their
86+
dispute. If you are unable to resolve the matter for any reason, or if the
87+
behavior is threatening or harassing, report it. We are dedicated to providing
88+
an environment where participants feel welcome and safe.
89+
90+
Reports should be directed to [email protected], the
91+
Project Steward(s) for UCP. It is the Project Steward’s duty to
92+
receive and address reported violations of the code of conduct. They will then
93+
work with a committee consisting of representatives from the Open Source
94+
Programs Office and the Google Open Source Strategy team. If for any reason you
95+
are uncomfortable reaching out to the Project Steward, please email
96+
<[email protected]>.
97+
98+
We will investigate every complaint, but you may not receive a direct response.
99+
We will use our discretion in determining when and how to follow up on reported
100+
incidents, which may range from not taking action to permanent expulsion from
101+
the project and project-sponsored spaces. We will notify the accused of the
102+
report and provide them an opportunity to discuss it before any action is taken.
103+
The identity of the reporter will be omitted from the details of the report
104+
supplied to the accused. In potentially harmful situations, such as ongoing
105+
harassment or threats to anyone's safety, we may take action without notice.
106+
107+
## Attribution
108+
109+
This Code of Conduct is adapted from the Contributor Covenant, version 1.4,
110+
available at
111+
<https://www.contributor-covenant.org/version/1/4/code-of-conduct/>

‎CONTRIBUTING.md‎

Lines changed: 247 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,247 @@
1+
<!--
2+
Copyright 2026 UCP Authors
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
-->
16+
17+
# How to Contribute
18+
19+
We would love to accept your patches and contributions to this project.
20+
21+
## Before you begin
22+
23+
### Sign our Contributor License Agreement
24+
25+
Contributions to this project must be accompanied by a
26+
[Contributor License Agreement](https://cla.developers.google.com/about) (CLA).
27+
You (or your employer) retain the copyright to your contribution; this simply
28+
gives us permission to use and redistribute your contributions as part of the
29+
project.
30+
31+
If you or your current employer have already signed the Google CLA (even if it
32+
was for a different project), you probably don't need to do it again.
33+
34+
Visit <https://cla.developers.google.com/> to see your current agreements or to
35+
sign a new one.
36+
37+
### Review our Community Guidelines
38+
39+
This project follows [Google's Open Source Community
40+
Guidelines](https://opensource.google/conduct/).
41+
42+
## Other Ways to Contribute
43+
44+
### Reporting Issues
45+
46+
If you find a bug, a mistake in the documentation, or have a feature request,
47+
please open an issue.
48+
This helps us track problems and improve the project.
49+
50+
### Discussions
51+
52+
If you want to start a conversation, share an idea, or ask a question, feel free
53+
to use GitHub Discussions.
54+
55+
## Contribution Process
56+
57+
### Significant Changes
58+
59+
Any significant change to the protocol requires a formal
60+
[Enhancement Proposal](../../issues/new?template=enhancement-proposal.md)
61+
and will require Tech Council (TC) approval. Because a change to the protocol
62+
requires the entire adopting ecosystem to implement the change, we consider
63+
significant changes to include:
64+
65+
- Core Schema Modifications: Any change to JSON schemas, including
66+
adding/updating fields or field descriptions
67+
- Protocol Changes: Alterations to communication flows or expected behaviors of
68+
operations
69+
- New API Endpoints: Introduction of entirely new capabilities or services.
70+
- Backwards Incompatibility: Any "breaking" change that requires a major version
71+
increment.
72+
73+
An [Enhancement Proposal](../../issues/new?template=enhancement-proposal.md)
74+
is a living artifact that tracks a proposal through its lifecycle:
75+
76+
- **Proposal:** Anyone can submit; idea is proposed and debated.
77+
- **Provisional:** TC majority vote to accept; enters working draft iteration.
78+
- **Implemented:** TC majority vote to finalize; code complete and merged.
79+
80+
Every [Enhancement Proposal](../../issues/new?template=enhancement-proposal.md)
81+
must follow a standard template requiring sections for a Summary, Motivation,
82+
Detailed Design, Risks, a Test Plan, and Graduation Criteria. This creates a
83+
permanent, public design record for the project's evolution.
84+
85+
### Capability Maturity Levels
86+
87+
After an Enhancement Proposal reaches "Provisional" status, the capability
88+
enters the maturity lifecycle with the following stability guarantees:
89+
90+
#### Working Draft
91+
92+
- **Version:** `Working Draft`
93+
- **Stability:** Breaking changes expected
94+
- **Status:** Prototyping, gathering feedback, iterating on design
95+
- **Exit criteria:** TC majority vote to advance
96+
97+
#### Candidate
98+
99+
- **Version:** `Candidate`
100+
- **Stability:** API surface stable; implementation details may evolve
101+
- **Status:** Early adopter implementations, production pilots
102+
- **Exit criteria:** TC majority vote to advance
103+
104+
#### Stable
105+
106+
- **Version:** `YYYY-MM-DD` (date-based version assigned)
107+
- **Stability:** Full backward compatibility within major version
108+
- **Status:** Production deployments
109+
110+
### Voting and decision making
111+
112+
The path below should be followed for resolving issues that are technical in
113+
nature.
114+
115+
- L1: routine changes (bug fixes, documentation, minor improvements) require
116+
approval from at least 2 Maintainers.
117+
- L2: Any technical issues that span across topics and/or cannot be resolved
118+
amongst maintainers and DWGs will be escalated to the TC. Significant changes
119+
affecting core protocol architecture must follow the Enhancement Proposal
120+
process, requiring TC approval before implementation.
121+
- L3: Any changes made to the Governance process (e.g updating the
122+
[GOVERNANCE.md](GOVERNANCE.md) file) or any changes that impact the core
123+
protocol’s scope or adoption, must be approved by Governance Council (GC).
124+
125+
The TC reserves the right to stop any discussions deemed non-critical to the
126+
protocol.
127+
128+
### Versioning
129+
130+
The base protocol uses date based versioning. Major version increments (breaking
131+
changes) require a majority Governing Council approval due to the high cost to
132+
the ecosystem. A quorum requires all Governing Council members (or appropriate
133+
representatives) to be present for decision-making. New features should
134+
typically be attempted through the extensions framework first. If an extension
135+
achieves significant usage, it can be considered for adoption into the next
136+
minor version of the core.
137+
138+
### Adding new extensions and capabilities to the core protocol
139+
140+
UCP is designed to be extensible while keeping the core protocol light. A
141+
core principle of UCP is to ensure that the set of extensions and capabilities
142+
defined in UCP have broad ecosystem support. Vendors should first create
143+
capabilities & extensions in vendor-specific namespace pattern
144+
(e.g. com.{vendor}.\*) for new use cases. Requests to add new capabilities and
145+
extensions should only be submitted when there is proven widespread adoption of
146+
vendor-specific capabilities and extensions. See
147+
[Spec URL Binding](https://ucp.dev/specification/overview/#spec-url-binding)
148+
and [Governance Model](https://ucp.dev/specification/overview/#governance-model)
149+
for more details on using namespace pattern for creating vendor-specific
150+
capabilities and extensions.
151+
152+
### Code Reviews
153+
154+
All submissions, including submissions by project members, require review. We
155+
use [GitHub pull requests](https://docs.github.com/articles/about-pull-requests)
156+
for this purpose.
157+
158+
### Pull Request Titles and Commit Messages
159+
160+
This repository enforces **Conventional Commits** for Pull Request titles.
161+
Your PR title must follow this format: `type: description`. If your change
162+
is a breaking change (e.g., removing a schema field or file), you **must**
163+
add `!` before the colon: `type!: description`.
164+
165+
**Common Types:**
166+
167+
- `feat`: A new feature
168+
- `fix`: A bug fix
169+
- `docs`: Documentation only changes
170+
- `style`: Changes that do not affect the meaning of the code
171+
- `refactor`: A code change that neither fixes a bug nor adds a feature
172+
- `perf`: A change to the code that improves performance
173+
- `test`: Adding missing tests or correcting existing tests
174+
- `chore`: Changes to the build process or auxiliary tools and libraries
175+
176+
**Examples:**
177+
178+
- `feat: add new payment gateway`
179+
- `fix: resolve crash on checkout`
180+
- `docs: update setup guide`
181+
- `feat!: remove deprecated buyer field from checkout`
182+
183+
### Linting and Automated Checks
184+
185+
We use linters and automated checks to maintain code quality and consistency.
186+
These checks run automatically via GitHub Actions when you open a pull request.
187+
Your pull request must pass all checks before it can be merged.
188+
189+
You can run many of these checks locally before committing by installing and
190+
using `pre-commit`:
191+
192+
```bash
193+
uv tool install pre-commit
194+
pre-commit install
195+
```
196+
197+
This will set up pre-commit hooks to run automatically when you `git commit`.
198+
199+
You can also run [super-linter](https://github.com/super-linter/super-linter)
200+
locally by running `./scripts/super_linter_local.py`. This assumes you have
201+
either [docker](https://www.docker.com/) or [podman](https://podman.io/)
202+
installed on your system.
203+
204+
### Submitting a Pull Request
205+
206+
1. Fork the repository and create your branch from `main`.
207+
2. Make your changes, ensuring you follow the setup instructions below.
208+
3. If you've installed `pre-commit`, it will run checks as you commit.
209+
4. Ensure your pull request title follows the Conventional Commits format.
210+
5. Fill out the pull request template in GitHub, providing details about
211+
your change.
212+
6. Push your branch to GitHub and open a pull request.
213+
7. Address any automated check failures or reviewer feedback.
214+
215+
## Local Development Setup
216+
217+
### Schema Development
218+
219+
Schemas live in `source/` and are published with `ucp_*` annotations intact.
220+
Agents use [ucp-schema](https://github.com/universal-commerce-protocol/ucp-schema)
221+
to resolve annotations for specific operations at runtime.
222+
223+
1. Ensure `ucp-schema` is installed:
224+
225+
```bash
226+
cargo install ucp-schema # from crates.io
227+
cargo install --git https://github.com/universal-commerce-protocol/ucp-schema # from git
228+
```
229+
230+
2. Make updates to JSON files in `source/`
231+
3. Run `ucp-schema lint source/` to validate syntax and references
232+
233+
If you change any JSON schemas, you may need to regenerate SDK client libraries.
234+
For example, to regenerate Python Pydantic models run
235+
`bash sdk/python/generate_models.sh`. Our CI system runs
236+
`scripts/ci_check_models.sh` to verify that models can be generated
237+
successfully from the schemas.
238+
239+
### Documentation Development
240+
241+
This project uses [uv](https://docs.astral.sh/uv/) for Python dependency management.
242+
243+
1. Install Python dependencies: `uv sync`
244+
2. Ensure `ucp-schema` is installed (see above)
245+
3. Run the development server: `uv run mkdocs serve --watch source`
246+
4. Open **<http://127.0.0.1:8000>** in your browser
247+
5. Before submitting, run `uv run mkdocs build --strict` to check for warnings/errors

0 commit comments

Comments
 (0)