docs(foundation): domain branching workflow and CODEOWNERS - #308
docs(foundation): domain branching workflow and CODEOWNERS#308YosefHayim wants to merge 2 commits into
Conversation
Why: Keep main shippable by routing all work through domain-named PRs with labels. What: BRANCHING.md, AGENTS/CONTRIBUTING/CLAUDE pointers, .github/CODEOWNERS path map. Impact: Process only; no runtime change. Domain GitHub labels are created on the remote.
YosefHayim
added
domain:foundation
|
🤖 CodeAnt AI — Review Status
|
Thanks for using CodeAnt! 🎉We're free for open-source projects. if you're enjoying it, help us grow by sharing. Share on X · |
codeant-ai
Bot
added
the
size:L
|
Warning Review limit reached
Next review available in: 58 minutes You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (5)
✨ Finishing Touches 💡 1🛠️ Fix failing CI checks 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Why: Claude-facing doc index should list the branching workflow. What: Add BRANCHING.md row to the CLAUDE.md doc family table. Impact: Docs only.
PR Summary by QodoDocs: add domain branching workflow and CODEOWNERS routing
AI Description
Diagram
High-Level Assessment
Files changed (4)
|
Code Review by Qodo
1. Branch prefixes inconsistent
|
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
| Full branching rules live in [`BRANCHING.md`](./BRANCHING.md). Short version: | ||
|
|
||
| - **Do not push commits to `main`.** Branch off `main` as `feat|fix|refactor|chore|docs/<domain>/<slug>`. | ||
| - Label the PR with the matching `domain:*` label (see BRANCHING.md). |
There was a problem hiding this comment.
1. Branch prefixes inconsistent 🐞 Bug ⚙ Maintainability
AGENTS.md and CONTRIBUTING.md summarize branch naming as feat|fix|refactor|chore|docs/<domain>/<slug>, but BRANCHING.md also allows test/ and ci/ prefixes. Contributors following the short versions may incorrectly conclude test/* and ci/* branches are disallowed.
Agent Prompt
## Issue description
The abbreviated branch naming guidance in `AGENTS.md` and `CONTRIBUTING.md` omits valid prefixes (`test/`, `ci/`) that are listed in `BRANCHING.md`, creating conflicting workflow documentation.
## Issue Context
`BRANCHING.md` is positioned as the source of truth, but the short versions should either (a) include the full prefix list, or (b) explicitly state they are examples and defer to `BRANCHING.md` for the canonical list.
## Fix Focus Areas
- CONTRIBUTING.md[87-93]
- AGENTS.md[7-11]
- BRANCHING.md[14-24]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
| | release | `domain:release` | `src/core/release/`, `releaseTrain/` (includes TestFlight) | | ||
| | testflight | `domain:testflight` | TestFlight-focused changes under release/CLI when that is the whole PR | |
There was a problem hiding this comment.
2. Releasetrain path typo 🐞 Bug ≡ Correctness
BRANCHING.md’s domain table lists releaseTrain/ without the src/core/ prefix used elsewhere, but the actual folder is src/core/releaseTrain/. This can mislead contributors using the table to locate the release-train code.
Agent Prompt
## Issue description
In `BRANCHING.md`, the `release` domain row includes `releaseTrain/` as a typical path, but the repo layout uses `src/core/releaseTrain/`. This is an incorrect/incomplete path in the documentation.
## Issue Context
`AGENTS.md` documents the repo layout and shows the correct `src/core/releaseTrain/` directory.
## Fix Focus Areas
- BRANCHING.md[56-61]
- AGENTS.md[44-48]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
5 issues found and verified against the latest diff
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="CONTRIBUTING.md">
<violation number="1" location="CONTRIBUTING.md:91">
P3: This new short version omits the `test` and `ci` branch types defined in BRANCHING.md (`test/<domain>/<slug>`, `ci/<domain>/<slug>`). While it is labeled a short version, the list is presented as the branch pattern contributors should use, so those two documented types are silently missing. Include them so the abbreviated form matches BRANCHING.md and AGENTS.md don't disagree.</violation>
</file>
<file name="AGENTS.md">
<violation number="1" location="AGENTS.md:9">
P3: Branch prefix list missing `test` and `ci` from BRANCHING.md's full list. Someone skimming AGENTS.md's summary might not realize `test/<domain>/<slug>` or `ci/<domain>/<slug>` branches are valid.</violation>
</file>
<file name=".github/CODEOWNERS">
<violation number="1" location=".github/CODEOWNERS:6">
P2: Missing `docs` domain path block. BRANCHING.md (canonical ownership map) and AGENTS.md both define `docs` as a domain covering README, CONTRIBUTING, ADR-only docs, and root architecture docs, but CODEOWNERS has no `# docs` section. Files like `/CONTRIBUTING.md`, `/README*.md`, `/docs/` (incl. ADRs), `/CONTEXT.md`, `/LANGUAGE.md`, `/PROJECT.md`, `/TECH.md` fall through to the default `*` rule instead of being assigned to the `docs` domain. The file comment says "Path blocks document domain ownership for routing" — omitting a documented domain means the map is incomplete.</violation>
</file>
<file name="BRANCHING.md">
<violation number="1" location="BRANCHING.md:17">
P3: The branch-naming rules use `<short-slug>` (lines 17–23), but the Daily flow and Epics sections use plain `<slug>` (`git switch -c feat/<domain>/<slug>`, `epic/<slug>`). Agents and contributors reading the workflow get two different placeholders for the same position, which is confusing right in the doc that is meant to standardize naming. Pick one placeholder (`<slug>` is simpler and already used in AGENTS.md/CONTRIBUTING.md) and use it consistently in all three spots.</violation>
<violation number="2" location="BRANCHING.md:59">
P3: The `release` domain row lists `releaseTrain/` without the `src/core/` prefix used for the other paths in this table, but the actual directory (per CODEOWNERS) is `src/core/releaseTrain/`. This inconsistency could mislead contributors trying to locate release-train code.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
|
|
||
| * @YosefHayim | ||
|
|
||
| # foundation — tooling, shared spine |
There was a problem hiding this comment.
P2: Missing docs domain path block. BRANCHING.md (canonical ownership map) and AGENTS.md both define docs as a domain covering README, CONTRIBUTING, ADR-only docs, and root architecture docs, but CODEOWNERS has no # docs section. Files like /CONTRIBUTING.md, /README*.md, /docs/ (incl. ADRs), /CONTEXT.md, /LANGUAGE.md, /PROJECT.md, /TECH.md fall through to the default * rule instead of being assigned to the docs domain. The file comment says "Path blocks document domain ownership for routing" — omitting a documented domain means the map is incomplete.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At .github/CODEOWNERS, line 6:
<comment>Missing `docs` domain path block. BRANCHING.md (canonical ownership map) and AGENTS.md both define `docs` as a domain covering README, CONTRIBUTING, ADR-only docs, and root architecture docs, but CODEOWNERS has no `# docs` section. Files like `/CONTRIBUTING.md`, `/README*.md`, `/docs/` (incl. ADRs), `/CONTEXT.md`, `/LANGUAGE.md`, `/PROJECT.md`, `/TECH.md` fall through to the default `*` rule instead of being assigned to the `docs` domain. The file comment says "Path blocks document domain ownership for routing" — omitting a documented domain means the map is incomplete.</comment>
<file context>
@@ -0,0 +1,69 @@
+
+* @YosefHayim
+
+# foundation — tooling, shared spine
+/CODE-STYLE.md @YosefHayim
+/BRANCHING.md @YosefHayim
</file context>
| - Branch off `main`; keep the gate green. | ||
| Full branching rules live in [`BRANCHING.md`](./BRANCHING.md). Short version: | ||
|
|
||
| - **Do not push commits to `main`.** Branch off `main` as `feat|fix|refactor|chore|docs/<domain>/<slug>`. |
There was a problem hiding this comment.
P3: This new short version omits the test and ci branch types defined in BRANCHING.md (test/<domain>/<slug>, ci/<domain>/<slug>). While it is labeled a short version, the list is presented as the branch pattern contributors should use, so those two documented types are silently missing. Include them so the abbreviated form matches BRANCHING.md and AGENTS.md don't disagree.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At CONTRIBUTING.md, line 91:
<comment>This new short version omits the `test` and `ci` branch types defined in BRANCHING.md (`test/<domain>/<slug>`, `ci/<domain>/<slug>`). While it is labeled a short version, the list is presented as the branch pattern contributors should use, so those two documented types are silently missing. Include them so the abbreviated form matches BRANCHING.md and AGENTS.md don't disagree.</comment>
<file context>
@@ -86,10 +86,14 @@ The same five steps apply to a `BuildEngine`, `CredentialsProvider`, or `Submitt
-- Branch off `main`; keep the gate green.
+Full branching rules live in [`BRANCHING.md`](./BRANCHING.md). Short version:
+
+- **Do not push commits to `main`.** Branch off `main` as `feat|fix|refactor|chore|docs/<domain>/<slug>`.
+- Label the PR with the matching `domain:*` label (see BRANCHING.md).
+- Keep the gate green.
</file context>
| - **Do not push commits to `main`.** Branch off `main` as `feat|fix|refactor|chore|docs/<domain>/<slug>`. | |
| - **Do not push commits to `main`.** Branch off `main` as `feat|fix|refactor|chore|test|ci|docs/<domain>/<slug>`. |
|
|
||
| ## Branching And PRs | ||
|
|
||
| - **Do not commit to `main`.** Branch as `feat|fix|refactor|chore|docs/<domain>/<slug>`, open a PR, label `domain:<domain>`, keep the gate green, delete the branch after merge. |
There was a problem hiding this comment.
P3: Branch prefix list missing test and ci from BRANCHING.md's full list. Someone skimming AGENTS.md's summary might not realize test/<domain>/<slug> or ci/<domain>/<slug> branches are valid.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At AGENTS.md, line 9:
<comment>Branch prefix list missing `test` and `ci` from BRANCHING.md's full list. Someone skimming AGENTS.md's summary might not realize `test/<domain>/<slug>` or `ci/<domain>/<slug>` branches are valid.</comment>
<file context>
@@ -1,9 +1,15 @@
+## Branching And PRs
+
+- **Do not commit to `main`.** Branch as `feat|fix|refactor|chore|docs/<domain>/<slug>`, open a PR, label `domain:<domain>`, keep the gate green, delete the branch after merge.
+- Domains: `foundation`, `config`, `credentials`, `build`, `apple`, `google`, `store`, `release`, `testflight`, `readiness`, `agents`, `cli`, `docs`.
+- Full rules, CODEOWNERS path map, and the optional `experiment/layered-history` lab: [BRANCHING.md](./BRANCHING.md).
</file context>
| 3. **Name branches by type and domain:** | ||
|
|
||
| ```text | ||
| feat/<domain>/<short-slug> |
There was a problem hiding this comment.
P3: The branch-naming rules use <short-slug> (lines 17–23), but the Daily flow and Epics sections use plain <slug> (git switch -c feat/<domain>/<slug>, epic/<slug>). Agents and contributors reading the workflow get two different placeholders for the same position, which is confusing right in the doc that is meant to standardize naming. Pick one placeholder (<slug> is simpler and already used in AGENTS.md/CONTRIBUTING.md) and use it consistently in all three spots.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At BRANCHING.md, line 17:
<comment>The branch-naming rules use `<short-slug>` (lines 17–23), but the Daily flow and Epics sections use plain `<slug>` (`git switch -c feat/<domain>/<slug>`, `epic/<slug>`). Agents and contributors reading the workflow get two different placeholders for the same position, which is confusing right in the doc that is meant to standardize naming. Pick one placeholder (`<slug>` is simpler and already used in AGENTS.md/CONTRIBUTING.md) and use it consistently in all three spots.</comment>
<file context>
@@ -0,0 +1,96 @@
+3. **Name branches by type and domain:**
+
+ ```text
+ feat/<domain>/<short-slug>
+ fix/<domain>/<short-slug>
+ refactor/<domain>/<short-slug>
</file context>
| | apple | `domain:apple` | `src/apple/`, Apple-only signing and ASC transport | | ||
| | google | `domain:google` | `src/google/`, Play client and reporting | | ||
| | store | `domain:store` | `src/core/store/`, listing, privacy, submit providers | | ||
| | release | `domain:release` | `src/core/release/`, `releaseTrain/` (includes TestFlight) | |
There was a problem hiding this comment.
P3: The release domain row lists releaseTrain/ without the src/core/ prefix used for the other paths in this table, but the actual directory (per CODEOWNERS) is src/core/releaseTrain/. This inconsistency could mislead contributors trying to locate release-train code.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At BRANCHING.md, line 59:
<comment>The `release` domain row lists `releaseTrain/` without the `src/core/` prefix used for the other paths in this table, but the actual directory (per CODEOWNERS) is `src/core/releaseTrain/`. This inconsistency could mislead contributors trying to locate release-train code.</comment>
<file context>
@@ -0,0 +1,96 @@
+| apple | `domain:apple` | `src/apple/`, Apple-only signing and ASC transport |
+| google | `domain:google` | `src/google/`, Play client and reporting |
+| store | `domain:store` | `src/core/store/`, listing, privacy, submit providers |
+| release | `domain:release` | `src/core/release/`, `releaseTrain/` (includes TestFlight) |
+| testflight | `domain:testflight` | TestFlight-focused changes under release/CLI when that is the whole PR |
+| readiness | `domain:readiness` | plan, doctor, snapshot, adopt, migrate, readiness probes |
</file context>
| | release | `domain:release` | `src/core/release/`, `releaseTrain/` (includes TestFlight) | | |
| | release | `domain:release` | `src/core/release/`, `src/core/releaseTrain/` (includes TestFlight) | |
1 participant
User description
Summary
BRANCHING.md: no direct commits tomain,feat|fix|…/<domain>/<slug>names,domain:*labels, epic rules, and the experimental layered-history lab refs.AGENTS.md,CONTRIBUTING.md, andCLAUDE.mdat that workflow..github/CODEOWNERSwith path → domain map (maintainer: @YosefHayim).domain:*labels (already on the repo).Test plan
CodeAnt-AI Description
Establish a domain-based branching and review workflow
What Changed
main, with one reviewable intent per branch.domain:*labeling, validation, review, and post-merge branch cleanup rules.Impact
✅ Fewer unreviewed changes to main✅ Clearer ownership for pull request reviews✅ More consistent branch and PR organization💡 Usage Guide
Checking Your Pull Request
Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.
Talking to CodeAnt AI
Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:
This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.
Example
Preserve Org Learnings with CodeAnt
You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:
This helps CodeAnt AI learn and adapt to your team's coding style and standards.
Example
Retrigger review
Ask CodeAnt AI to review the PR again, by typing:
Check Your Repository Health
To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.
Summary by cubic
Adds
BRANCHING.mdand.github/CODEOWNERSto formalize a domain-based branching workflow and route reviews by path. UpdatesAGENTS.md,CONTRIBUTING.md, andCLAUDE.mdto point to the new process. No runtime changes.feat|fix|refactor|chore|docs/<domain>/<slug>; never commit tomain; delete branches after merge.domain:<name>and keep the gate green (pnpm typecheck && pnpm lint && pnpm lint:style && pnpm docs:check && pnpm test && pnpm build).@YosefHayim); consider enabling “Require review from Code Owners”.Written for commit bb99acb. Summary will update on new commits.