diffinery/CONTRIBUTING.md
| 1 | # Contributing to Diffinery |
| 2 | |
| 3 | Thanks for your interest in Diffinery. Bug reports, fixes, documentation, compatibility |
| 4 | reports and new features are all welcome, from people and from AI agents working for |
| 5 | them. |
| 6 | |
| 7 | ## Where development happens |
| 8 | |
| 9 | Diffinery is developed on Diffinery itself, at |
| 10 | [diffinery.com/codician/diffinery](https://diffinery.com/codician/diffinery). Its CI, |
| 11 | pull requests, code review and deploys all run there. |
| 12 | [github.com/codician-team/diffinery](https://github.com/codician-team/diffinery) is a |
| 13 | mirror that follows `main`. |
| 14 | |
| 15 | - **If you have an account on diffinery.com**, open issues and pull requests there. |
| 16 | - **If you don't**, open them on the GitHub mirror. Accounts on diffinery.com are by |
| 17 | invitation for now, so this is the usual path for new contributors. A maintainer lands |
| 18 | accepted pull requests on Diffinery and they come back to GitHub with the next sync; |
| 19 | the GitHub pull request is then closed with a link to the change. The mirror rewrites |
| 20 | commit authorship, so look for the change by its title or pull request number rather |
| 21 | than by commit SHA. |
| 22 | |
| 23 | Security problems are the exception: report them privately, never in an issue or pull |
| 24 | request. See [SECURITY.md](SECURITY.md). |
| 25 | |
| 26 | ## Before you start |
| 27 | |
| 28 | - For anything bigger than a small fix, open an issue first and describe what you want to |
| 29 | change, so we can agree on the approach before you spend time on it. |
| 30 | - Check [Compatibility with GitHub Actions](https://diffinery.com/docs/actions/compatibility) |
| 31 | before reporting a workflow difference: known gaps are listed there. |
| 32 | - Please follow the [Code of Conduct](CODE_OF_CONDUCT.md). |
| 33 | |
| 34 | ## Set up a development environment |
| 35 | |
| 36 | You need Node.js 22 and pnpm 10 (the repository pins `pnpm@10.28.0`; `corepack enable` |
| 37 | picks it up). Docker is only needed to build the runner image. No Cloudflare account is |
| 38 | needed: everything runs locally under `wrangler dev`. |
| 39 | |
| 40 | ```sh |
| 41 | pnpm install |
| 42 | pnpm -r build # runner agent, web islands and docs |
| 43 | pnpm --filter @diffinery/app db:migrate:local # local D1 |
| 44 | pnpm dev # http://localhost:8787, signed in as dev@diffinery.local |
| 45 | ``` |
| 46 | |
| 47 | ## Tests |
| 48 | |
| 49 | ```sh |
| 50 | pnpm -r typecheck |
| 51 | pnpm -r test # unit tests (Vitest) |
| 52 | pnpm --filter @diffinery/app e2e # end-to-end: wrangler dev, real git, the runner agent and Chromium |
| 53 | ``` |
| 54 | |
| 55 | The end-to-end suite pushes real repositories with `git`, runs their workflows through the |
| 56 | real runner agent, drives the MCP server and the REST API with `@octokit/rest`, and signs |
| 57 | in with passkeys in Chromium with a virtual authenticator. It takes a while and uses a lot |
| 58 | of memory for the large-push tests; run the file you changed first, for example |
| 59 | `cd apps/diffinery && node --test --test-timeout=600000 test/e2e/registry.test.mjs`. |
| 60 | |
| 61 | Pull requests must pass CI (typecheck, the Worker bundle and the unit tests) and the |
| 62 | end-to-end shards before they merge. Tests must not depend on the speed of the machine |
| 63 | they run on. |
| 64 | |
| 65 | ## Conventions |
| 66 | |
| 67 | - **TypeScript everywhere**, in strict mode, sharing code through the workspace packages in |
| 68 | `packages/`. Keep dependencies few: the git core (`packages/git-core`) needs only `pako` and `diff`. |
| 69 | - **Comments say why**, in plain sentences, next to the code they explain. Match the |
| 70 | density and style of the code around your change. |
| 71 | - **Docs ship with the feature.** Every user- or admin-visible change updates the pages in |
| 72 | `apps/diffinery/docs` (served at [diffinery.com/docs](https://diffinery.com/docs), also as |
| 73 | Markdown and in `llms.txt`). Write for people and for AI agents: short sentences, exact |
| 74 | names of buttons, settings, endpoints and flags, and tables for reference material. |
| 75 | - **GitHub compatibility.** Where GitHub has an API, a workflow feature or an event, |
| 76 | Diffinery follows it, so existing tools (git, `gh`, Octokit, actions) work unchanged. |
| 77 | When Diffinery has to differ, say so in the docs. |
| 78 | - **Database migrations.** D1 migrations live in `apps/diffinery/migrations`. Use the next |
| 79 | free number and never edit a migration that has shipped. |
| 80 | - **Security first.** Agents never get a bypass: guardrails are enforced on the server for |
| 81 | git, REST, MCP and the web UI alike. Never log secrets or tokens. Changes to sign-in, |
| 82 | tokens, permissions, secrets or the runner sandbox get extra review. |
| 83 | - **UI and product conventions** (passkeys first, Kumo components, no native `<select>` or |
| 84 | checkboxes) are in [docs/PREFERENCES.md](docs/PREFERENCES.md). |
| 85 | |
| 86 | ## Pull requests |
| 87 | |
| 88 | - Keep each pull request to one change, with a title that says what it does |
| 89 | ("Merge queue: rebuild groups behind a failed one") and a description of why and how it |
| 90 | was tested. The [pull request template](.github/pull_request_template.md) has the |
| 91 | checklist. |
| 92 | - Changes to files under `.github/workflows` always need a maintainer to merge them, on |
| 93 | purpose: agents can't land workflow changes. |
| 94 | - Pull requests are squash-merged. |
| 95 | |
| 96 | ## AI agents |
| 97 | |
| 98 | Agents are welcome contributors. An agent working on this repository should follow the |
| 99 | same conventions, run the tests before asking for review, and say in the pull request |
| 100 | which person it works for. The [docs for AI agents](https://diffinery.com/docs/agents/docs-for-agents) |
| 101 | explain how to read the documentation as Markdown and over MCP. |
| 102 | |
| 103 | ## License |
| 104 | |
| 105 | Diffinery is licensed under the [Apache License 2.0](LICENSE). By contributing, you agree |
| 106 | that your contributions are licensed under the same license, as section 5 of the license |
| 107 | describes. |