Contributing to Portage¶
Firstly, thanks so much for taking an interest! Building this project has been a lot of fun and I've always intended it to be a group project that anyone can contribute too and add their ideas!
As Portage is an open workspace, based on a collection of Ruby gems that expose commerce backends to AI shopping agents over both MCP and UCP there's a ton of things we can add and do, feel free to fork, mod and cook up any wild ideas you like!
Bug reports, adapters, new features, docs, and spec-conformance fixes are very welcome inded.
Participation is governed by the Code of Conduct — in short: be decent, and never paste real credentials, tokens, or customer PII into an issue or PR.
Before anything else: this project is still slightly pre-1.0 and still tracking a moving spec due to how UCP is evolving.
The capability/adapter contract is not settled, so things are likely to change. But just go with it, it's all good.
Table of contents¶
- Ways to contribute
- Code of conduct
- Reporting a bug
- Reporting a security issue
- Development setup
- Repository layout
- Exploring the codebase with graphify (optional)
- Running the tests
- Writing a new platform adapter
- Coding style
- Commit messages
- Opening a pull request
- Changelogs
- Documentation and the design log
- Releasing (maintainers)
- License
Ways to contribute¶
- A new platform adapter — the most welcome kind of PR. See Writing a new platform adapter.
- Bug fixes, especially wire-shape mismatches against a real store. Include what the store actually returned.
- Spec conformance — if Portage's manifest, schemas, or tool shapes have drifted from what UCP or MCP now specify, a PR with the spec citation is very useful.
- Docs — the README,
docs/cli-usage-tutorial.md, the agentskills/, and the walkthroughs. - Reproductions — a failing spec with no fix attached is still a good contribution.
Code of conduct¶
This project ships a Code of Conduct (Contributor Covenant 2.1) that applies to issues, pull requests, and discussions. Two clauses matter more here than in most repos, because Portage handles live commerce credentials: never post real credentials, tokens, payment instruments, or customer PII, and report security issues privately rather than in a public issue.
Reporting a bug¶
Please open an issue at tomtom87/Portage using the Bug report template, which asks for the following to help us track down what's happening:
- Which gem and version (
portage-ucp0.8.0,portage-cli0.8.0, …) and your Ruby version. - What you ran and what happened, with the exact error text and backtrace — not a paraphrase.
- For anything touching a live store: the platform, and the request/response shape with credentials, tokens, and PII redacted.
- Ideally, a failing spec or a minimal script against
Portage::Ucp::ReferenceAdapter.
Please can you also search existing issues first. A +1 or "me too" on an open issue is ideal... no worries if you didn't see one, no biggie.
Note that some failures against live Shopify stores are not Portage bugs: real UCP tool
calls currently hit a platform-side allowlist gate and come back Tool not found. See
docs/ucp-tool-gating-investigation.md before
filing.
Reporting a security issue¶
Do not open a public issue. Report it privately to the maintainer — see
SECURITY.md, which also documents the trust boundaries Portage assumes
(the Marshal-backed idempotency store, payment-token handling, the policy guards). If
you're unsure whether something is a security issue, treat it as one and report privately.
Development setup¶
Requires Ruby >= 3.2 (CI runs 3.2 and 3.4).
Each gem owns its own bundle. There is no root Gemfile, no shared lockfile, and no
cross-gem run-order dependency. Install per gem, in that gem's directory:
Adapter gems and the CLI resolve the core gem by path, so a local change to portage-ucp
is picked up by the gem you're testing without a release.
Never commit .env — it holds live credentials. Copy .env.example and fill it in locally.
Repository layout¶
| Directory | What it is |
|---|---|
portage-ucp/ |
Protocol core: the Adapter contract, capability registry, manifest builder, MCP server wrapper, schema validator, conformance kit. No commerce-backend deps. |
portage-ucp-client/ |
Client side — discovering and calling a UCP store. |
portage-cli/ |
The portage CLI (find, buy, history, payment, policy). |
portage-ucp-journal/ |
Audit journal. |
portage-ucp-{shopify,wix,woocommerce,bigcommerce,magento,etsy,instagram}/ |
Platform adapters. shopify is the most complete reference. |
docs/ |
Design log, tutorials, investigations. |
skills/ |
Agent skills (shop-via-ucp, browse-via-ucp, serve-via-ucp). |
Exploring the codebase with graphify (optional)¶
graphify turns a gem into a queryable knowledge graph — handy for orienting yourself before a change ("what calls Dispatcher?", "how does buy reach PolicyGuard?"). It is entirely optional and nothing in the build depends on it.
uv tool install graphifyy # or: pipx install graphifyy
graphify install # registers the /graphify skill with your coding agent
Then, from your agent, build a graph for the gem you're working on:
Code is parsed locally with tree-sitter (no LLM, no API key). Only READMEs and CHANGELOGs go through your agent, so expect a small token cost per gem. Outputs land in <gem>/graphify-out/ — open graph.html in a browser or read GRAPH_REPORT.md, and query from the CLI:
cd portage-cli
graphify query "how does buy enforce the spending policy?"
graphify path "Portage::Cli::Buy" "Portage::Ucp::PolicyGuard"
To see the whole stack at once, graph each gem and merge them at the repo root:
graphify merge-graphs portage-cli/graphify-out/graph.json portage-ucp/graphify-out/graph.json \
portage-ucp-client/graphify-out/graph.json --out graphify-out/graph.json
Note that the merge keeps each gem's nodes separate: graphify doesn't link a reference like Portage::Ucp::Policy in portage-cli to its definition in portage-ucp, so questions across gem boundaries will come back incomplete.
graphify-out/ is gitignored — graphs go stale with every commit, so please don't commit them. Run graphify update <gem> to refresh a graph after you pull.
Running the tests¶
Per gem, from that gem's directory:
Across every gem, from the workspace root — this shells into each gem in turn and stops at the first failure:
And the adapter-contract check, which fails if a bundled adapter gem's suite doesn't run the shared conformance kit:
Run at least the gem(s) you touched before opening a PR. CI
(.github/workflows/ci.yml) runs rspec and rubocop for every
gem on two Ruby versions plus rake conformance, but finding it locally is faster than
waiting on the matrix.
New behavior needs a spec. Bug fixes need a spec that fails before the fix.
Writing a new platform adapter¶
The shape of it:
class MyAdapter < Portage::Ucp::Adapter
def search_catalog(query:, limit:) = ...
def get_product(product_id:) = ...
def create_cart(line_items:, idempotency_key:) = ...
# override only the capabilities you support — the rest stay unadvertised
end
Read Portage::Ucp::Adapter for the full method contract and
Portage::Ucp::ReferenceAdapter (portage-ucp/lib/portage/ucp/reference_adapter.rb) for a
complete in-memory implementation of every capability. portage-ucp-shopify is the
reference against a real API.
Then make it prove itself against the contract — schema-valid output can still break the behavioral guarantees (an idempotency key that doesn't actually dedup, a raw PAN reaching the adapter, a capability advertised but not round-tripping):
# spec/spec_helper.rb
require "portage/ucp/rspec"
# spec/my_adapter_spec.rb
RSpec.describe MyAdapter do
it_behaves_like "a portage adapter" do
let(:adapter) { MyAdapter.new(client: my_test_client) }
let(:existing_product_id) { "known-good-product-id" }
end
end
Every example skips itself when the adapter doesn't advertise the capability it needs, so a
catalog-and-checkout-only adapter still runs the kit cleanly. Include
Portage::Ucp::Support::Idempotency (as every bundled adapter does) and the dedup example
checks the dedup table itself rather than just comparing two calls' output.
Checklist for a bundled adapter gem (one living in this repo):
- Gem directory with its own
Gemfile, gemspec,spec/,.rubocop.yml,README.md, andCHANGELOG.md, following an existing adapter's layout. spec/portage/ucp/<platform>/conformance_spec.rbrunning the shared kit.- Added to
GEMSandADAPTER_GEMSin the rootRakefile. - Added to the
gem:matrix in.github/workflows/ci.yml. - Added to the gem table in the README.
- No live network in specs — stub with
webmock.
An adapter you publish as your own gem outside this repo is equally welcome; open an issue and we'll link it from the README.
Coding style¶
RuboCop is the arbiter — each gem has its own .rubocop.yml, and CI enforces it. Beyond
that:
- Double-quoted strings, Ruby >= 3.2 syntax.
- Match the surrounding code's naming and idiom rather than importing a house style.
- Comments are sparse and explain why, not what. Prefer a comment that records a decision or a trap over one that narrates the line below it.
- No new runtime dependency in
portage-ucpwithout discussing it first — the core gem staying dependency-light (and RSpec-free at runtime) is deliberate. - Nothing is permissive by default: new capabilities stay unadvertised unless implemented, and new credential or payment paths need an explicit guard, not a trusting default.
Commit messages¶
This repo keeps a story-style history. Conventional Commits prefixes (feat:, fix:) are
not used.
- Imperative mood, sentence case, no trailing period:
Read the catalog through Storefront, not Admin - One logical change per commit. If a PR touches a contract and its adapters, split by dependency order — the thing being inherited from first.
- The subject usually stands alone. Add a body only when the change is genuinely deep and the why can't fit in the subject.
- Keep build/lock-file churn (
Gemfile.lockrefreshes, version bumps) in its own commit.
Opening a pull request¶
- Branch off
main. Name it for the change, not the ticket. - Make sure
rspecandrubocoppass for every gem you touched, andrake conformanceif you touched an adapter. - Update the affected gem's
CHANGELOG.md(see below) and the README if you changed anything a user sees. - Fill in the PR template's Summary: a narrative explanation of what changed and why, in paragraphs, covering the context that isn't obvious from the commits. Not a bullet list restating the diff.
- Open it and let CI run. Keep the PR focused — unrelated cleanups in the same PR make it slower to review, not faster.
- Address review feedback by amending or fixing up into the commit it belongs to, so the merged history reads as if the mistake never happened, rather than adding a "fix review comment" commit.
Changelogs¶
Each gem keeps its own CHANGELOG.md for its own API; the root
CHANGELOG.md covers the workspace, shared docs, and anything spanning more
than one gem. Format loosely follows Keep a Changelog.
Add your entry under the unreleased heading of every changelog your change affects. Mark
anything that breaks an existing caller as breaking in the entry text — pre-1.0 means
breaking changes are allowed, not that they go unannounced.
Documentation and the design log¶
docs/design-log.md
is the decision history: numbered sections, each one a dated record of a decision, what
was rejected, and why. It's the reason most "why is it like this?" questions have an
answer.
You don't need to add a design-log section to contribute. Do add one (next number, dated,
same shape as the existing entries) when your PR settles a question rather than just
implementing one — a contract change, a rejected alternative worth recording, or a platform
behavior you had to reverse-engineer. Reference existing sections as §N.
Building the docs locally¶
The published documentation site (Read the Docs, MkDocs Material) lives under docs/ and
mkdocs.yml at the repo root. It pulls each gem's own README in via
mkdocs-include-markdown-plugin rather than duplicating content, so most of what you'd
edit is still each gem's own README.md.
python3 -m venv .venv && source .venv/bin/activate
pip install -r docs/requirements.txt
mkdocs serve # http://127.0.0.1:8000, live-reloads on save
mkdocs build --strict # what CI/Read the Docs runs — fails on any broken link or nav issue
docs/design-log.md and docs/plans/** are excluded from the built site and from the
generated llms.txt/llms-full.txt (see exclude_docs in mkdocs.yml) — they're
internal working documents, not published documentation.
Releasing (maintainers)¶
gem build must run from inside the gem's own directory — every gemspec's
spec.files = Dir["lib/**/*.rb", ...] resolves against the current directory, so building
from the workspace root silently produces a package with no lib/ (this shipped once; see
the 0.7.1 postmortem in the changelog). The rake tasks encode that:
rake release_check[portage-ucp] # build from the right dir, install and require the result
rake publish_all # build, verify, and push every gem whose version isn't on rubygems.org
Only push once release_check passes. RubyGems MFA prompts for a fresh OTP per push, so
publish_all pauses at each one.
License¶
By contributing, you agree that your contributions are licensed under the MIT License, the same terms as the rest of the project.