Skip to content

Tell contributors to check for duplicates and the right branch - #8609

Open
ParadokS81 wants to merge 4 commits into
omacom:quattrofrom
ParadokS81:contributing-branch-and-duplicate-checks
Open

ParadokS81 wants to merge 4 commits into
omacom:quattrofrom
ParadokS81:contributing-branch-and-duplicate-checks

Conversation

@ParadokS81

Copy link
Copy Markdown

contributing.md sends contributors straight from "found a bug" to filing. Two steps in between prevent wasted work on both sides, and I hit both writing #8597.

Check for an existing report

Searching only issues misses open PRs. I found two bugs in omarchy-font-set; one was already #6957 with PR #6958 open and a better fix than I would have written. Searching issues alone would not have surfaced it.

Verify against the default branch

master is not where development happens and can be weeks behind a shipped release:

default branch   2026-08-27   (current)
master           2026-08-14   (13 days stale, older than the installed 4.0.1)

I fetched bin/omarchy-font-set from master to check whether a bug still existed and got a version older than my own installed copy — missing the fontconfig rewrite that had already shipped. A bug "confirmed" that way may already be fixed, or simply not be the code users run.

The added section teaches the check (gh repo view --json defaultBranchRef) rather than naming today's branch, so it stays correct when the branch changes.

Test guidance

AGENTS.md asks for "focused automated tests for the area you changed"; this file said to run ./test/all before pushing, and calls AGENTS.md the authority. On my machine ./test/all reports 6 failures on a clean tree — attached-monitor counts, a missing sibling checkout, a network-dependent check — none related to any change. Read as a gate, that blocks valid PRs. Aligned the wording with AGENTS.md and noted how to tell an environmental failure from a real one.

Docs only; no behaviour change.

The skill sends contributors straight to filing without two steps that
prevent wasted work: searching for an existing report, and confirming the
bug against the branch development happens on. `master` is weeks behind a
shipped release, so a bug verified there can be already fixed or simply
not the code users run.

Also aligns the test guidance with AGENTS.md, which asks for the focused
suite rather than ./test/all.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Copilot AI balanced review requested due to automatic review settings August 27, 2026 15:15

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Updates contributor guidance to reduce duplicate reports and verify bugs against current development code.

Changes:

  • Adds issue and PR search guidance.
  • Adds default-branch verification instructions.
  • Clarifies focused test execution and environmental failures.

Tip

If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.


💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment on lines +98 to +99
Confirm by stashing the change and re-running, then say what you ran in the
PR.
Comment on lines +32 to +35
Check the bug against the branch development actually happens on, not against
whatever `git clone` or a raw URL hands you. `master` is not it, and can be
weeks behind a shipped release — so a bug "confirmed" there may already be
fixed, or the code may not match what users are running:
…ctually comes from

A plain git clone checks out the default branch; the stale-master trap is an
older checkout or a raw URL pinned to master. And a bare git stash leaves new
files in place, so the baseline rerun would still include the change.
@ParadokS81

Copy link
Copy Markdown
Author

Both notes addressed: the stash step now says git stash -u / git stash pop, and the default-branch paragraph no longer claims a fresh git clone lands on master — it names the actual traps (an older checkout, or a raw URL pinned to master).

@rdoupe

rdoupe commented Aug 30, 2026

Copy link
Copy Markdown
Contributor

Worth knowing before this gets reviewed: the guidance here is right, but default/agents/skills/omarchy/contributing.md is not read by the agents it is aimed at.

So for the PR-submission path, AGENTS.md is the file that actually gets read. I opened #9095 putting the search-first guidance there. The issue-reporting path is a different story: an agent reporting a bug does load the skill, so guidance in the skill's reporting guide (post-#6718, reporting-issues.md) is well placed for that.

…nt name

The repository moved from basecamp/omarchy to omacom/omarchy, and quattro's copy of this file already names the new one. gh search does not follow the rename: both search commands fail with "cannot be searched" against the old name.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@omarchybot

Copy link
Copy Markdown
Collaborator

Reviewed by Claude Opus 5.5. I read the change against the repository at its head and against current quattro. It is Markdown only, so nothing was run on a worker. The second opinion (Codex Medium) did not run: the day's review budget was already spent. This has had one model's reading, not two.

One defect, now fixed on your branch in fb314c4: the repository has moved to omacom/omarchy, and gh search does not follow the rename. Both new search commands failed with "cannot be searched" against basecamp/omarchy, so the section's main instruction did nothing. The commit points those two commands, and the gh repo view one, at omacom/omarchy, which is what quattro's copy of this file already uses. The branch still merges cleanly into quattro.

Everything else checks out. ./test/all, ./test/cli and ./test/shell exist and match the Tests section of AGENTS.md. ./test/all does depend on the machine: test/shell.d/config-test.sh looks for a sibling omarchy-pkgs checkout, and test/shell.d/monitor-recovery-test.sh reads the attached monitors. git stash -u and git stash pop behave as described. A fresh clone does land on the default branch, which is quattro. Copilot's two earlier notes were addressed in 8d3d473.

This now waits on the maintainer, because two open pull requests overlap with it. #6718 deletes contributing.md and sends upstream work to the repository's AGENTS.md, so landing either one changes what the other should be. #9095 adds the "search open PRs first" guidance to AGENTS.md instead, and that covers the first of the three sections here. Which of these to keep, and where the guidance should live, is a call for the maintainer.

@greptile-apps

greptile-apps Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerConfidence Score: 5/5

[Low risk] Updates contributor guidelines with duplicate and branch checks.

The PR appears safe to merge, though the open suggestion about capped duplicate searches remains.

Findings

  1. P2 Search results are capped ▶

Summary

This documentation change tells contributors to search issues and PRs, verify bugs against the default branch and their installed copy, and run focused tests. The latest edit adds a baseline-check option for changes that have already been committed.

Reviews (2) · Last reviewed commit: "contributing: give a baseline check that..."

Comment on lines +24 to +25
gh search issues --repo omacom/omarchy "<keywords>" --limit 10
gh search prs --repo omacom/omarchy "<keywords>" --limit 10

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Search results are capped

The --limit 10 options can hide an existing issue or PR if it falls below the first ten matches. That makes a duplicate report more likely, despite this section’s purpose. Consider removing the cap or telling contributors to broaden the search when results are truncated.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

…mmitted

git stash -u removes nothing once the change is committed, so the rerun still tests the change and cannot show a failure is environmental. Switching to the default branch covers that case.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@omarchybot

Copy link
Copy Markdown
Collaborator

Reviewed again by Claude Opus 5.5 after Greptile's two notes on fb314c4. The second opinion (Codex Medium) did not run this time either, because the day's review budget was spent, so this has still had only one model's reading.

One defect, now fixed on your branch in 8be9894: the baseline check said to git stash -u and re-run, but once the change is committed the stash takes nothing away, so the re-run still tests the change and can't show that a failure is environmental. The sentence now says to stash while the change is uncommitted, or git switch to the default branch once it is committed. This is Greptile's second note.

Greptile's first note, that --limit 10 can hide a match, is left as it is. It's a choice about how much to read rather than a broken command, and it's yours to make. Both search commands return results against omacom/omarchy, gh repo view reports quattro as the default branch, and the test entry points and the machine-dependent tests it names (test/shell.d/config-test.sh, test/shell.d/monitor-recovery-test.sh) exist. It's Markdown only, so nothing ran on a worker. The branch still merges cleanly into quattro.

It still waits on the maintainer for the reason given earlier: #6718 removes contributing.md, and #9095 puts the search-first guidance in AGENTS.md, so which of them lands decides where this guidance belongs.

@omarchybot omarchybot removed the documentation Improvements or additions to documentation label Oct 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants