From 0a11839a1c9e1a3508f8ea769076090b311dfd95 Mon Sep 17 00:00:00 2001 From: Ben Senescu <44480372+bensenescu@users.noreply.github.com> Date: Tue, 11 Aug 2026 21:51:15 -0400 Subject: [PATCH] Clarify contribution and pull request guidance (#457) --- .../skills/simple-issue-description/SKILL.md | 80 +++++++++++++++++++ .../agents/openai.yaml | 4 + README.md | 10 ++- docs/CONTRIBUTING.md | 73 ++++++++++++----- 4 files changed, 144 insertions(+), 23 deletions(-) create mode 100644 .agents/skills/simple-issue-description/SKILL.md create mode 100644 .agents/skills/simple-issue-description/agents/openai.yaml diff --git a/.agents/skills/simple-issue-description/SKILL.md b/.agents/skills/simple-issue-description/SKILL.md new file mode 100644 index 0000000..1c096d2 --- /dev/null +++ b/.agents/skills/simple-issue-description/SKILL.md @@ -0,0 +1,80 @@ +--- +name: simple-issue-description +description: Turn a rough bug report, feature request, support note, or pull request into a short, plain-language issue focused on the problem and desired behavior. Use when a contributor asks to simplify an issue, explain what a PR is for, create the corresponding issue for a PR, remove implementation detail from a report, or invokes /simple-issue-description. +--- + +# Simple Issue Description + +Write an issue a maintainer can understand in under a minute. Focus on what someone experiences and what should happen instead. + +## Workflow + +1. Read the supplied notes, conversation, issue, PR description, or diff. In a PR, also check for spec, design doc, or README changes — they often state the intent better than the description does. +2. Identify the concrete problem. State who or what is affected when the source makes that clear. +3. Describe the desired behavior without prescribing an implementation. +4. Keep only context that helps someone understand or reproduce the problem. +5. If the source is a PR or diff, describe the problem the change tries to solve, not the files or code it changes. +6. Draft the issue immediately unless the problem and desired behavior cannot be determined. In that case, ask one short clarifying question. + +One issue per problem. If the source bundles unrelated problems, draft the issue for the most significant one, list the others in a line each, and tell the contributor to split them into separate issues and separate pull requests. + +If the source adds a capability instead of fixing a misbehavior, do not stage the absence as a bug. Describe what a user cannot do today and the full user experience of the feature: who uses it, from where, and what they see. + +Do not invent user impact, reproduction steps, or certainty that the source does not support. If the source only shows cleanup, refactoring, or a possible code smell, say that no concrete problem is clear instead of manufacturing an issue — this rule wins over step 6. Reply with two or three sentences: what the source shows, and what evidence would make it issue-worthy. + +If the source fixes a security weakness that is not already public, do not draft a public issue describing it. Suggest reporting it privately to the maintainer instead. + +## Writing rules + +- Use plain language and short sentences. +- Keep the issue under 200 words unless it is clear that more is necessary to describe the reproduction steps or a large feature. +- Lead with behavior, not code, architecture, or the proposed fix. A one-sentence plain-language cause is fine when the symptom cannot be understood without it. +- Keep technical details only when they are necessary to reproduce or understand the problem. Limits and defaults that make the symptom make sense (batch sizes, quotas, caps) count as necessary. +- Preserve useful evidence such as error messages, screenshots, links, and documentation references. +- Do not mention that AI wrote or reviewed the issue. +- Avoid filler, praise, roadmap language, and exhaustive edge cases. +- Use the contributor's level of certainty. Do not present a guess as a confirmed bug; write "can" or "appears to" when the source describes a risk rather than an observed failure. + +## Output format + +The first line is the issue title — when filing on GitHub, put it in the title field instead of repeating it in the body. For a missing capability, title the outcome ("Flag pages with no structured data") rather than a fake bug ("Audits never mention structured data"). + +Omit the **Extra context** section when there is nothing useful to add. Constraints and scope notes belong there, including what is not affected when a maintainer would reasonably worry that it is. + +```markdown +# + +## TL;DR + + + +## What is happening? + + + +## What should happen? + + + +## Extra context + + +``` + +## Example + +```markdown +# The chat jumps away from messages I am reading + +## TL;DR + +When I scroll up to read an older message, a new response moves me back to the bottom of the chat. The chat should stay where I left it until I choose to return to the latest message. + +## What is happening? + +New responses automatically scroll the chat to the bottom, even when I am reading earlier messages. + +## What should happen? + +Keep my current scroll position and show that a new message is available. +``` diff --git a/.agents/skills/simple-issue-description/agents/openai.yaml b/.agents/skills/simple-issue-description/agents/openai.yaml new file mode 100644 index 0000000..da55673 --- /dev/null +++ b/.agents/skills/simple-issue-description/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Simple Issue Description" + short_description: "Turn rough reports into clear, simple issues" + default_prompt: "Use $simple-issue-description to turn this report or PR into a clear issue focused on the problem and desired behavior." diff --git a/README.md b/README.md index 7c9f5e5..2e08abd 100644 --- a/README.md +++ b/README.md @@ -64,7 +64,15 @@ See [`docs/LOCAL_DEVELOPMENT.md`](./docs/LOCAL_DEVELOPMENT.md). ## Contributing -Contributions are very welcome. See [`docs/CONTRIBUTING.md`](./docs/CONTRIBUTING.md). +Creating clear issues is the best way to contribute. + +Read more here: [`docs/CONTRIBUTING.md`](./docs/CONTRIBUTING.md) + +We have this skill: `/simple-issue-description` which helps. + +```sh +npx skills add every-app/open-seo --skill simple-issue-description +``` ## Community diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 04bd9be..1004c98 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,33 +1,62 @@ # Contributing to OpenSEO -Contributions are very welcome. +Thank you for your interest in contributing to OpenSEO! -- Open an issue for bugs, UX friction, or feature requests. -- Open a PR if you want to implement a feature directly. -- Community-driven improvements are prioritized, and high-quality PRs are encouraged. +We deeply appreciate the time and enthusiasm that people bring to the project. One of my favorite things is seeing the forks that people make building off of OpenSEO. -If you want to contribute but are unsure where to start, open an issue and describe what you want to build. You can also join the [Discord](https://discord.gg/c9uGs3cFXr) to talk through ideas first. +## Why aren't we accepting PRs? -## Local development +Short Answer: AI & Security -See [LOCAL_DEVELOPMENT.md](./LOCAL_DEVELOPMENT.md) for how to run the app locally. +I love using AI to write code as much as anyone. But, it makes it very challenging to assess how much thought and effort went into external pull requests. As a result, I spend a lot of time reviewing, testing and iterating on many external PRs and it ends up slowing down overall development. -## Guidelines +Additionally, as OpenSEO becomes more popular, I'm concerned about malicious contributors attempting to sneak in code that slips through review. -- Keep PRs focused: one feature or fix per PR. -- For larger features, open an issue first so we can align on the approach before you invest time. -- Before requesting review, run the same root checks used by CI: +## Issues: The best way to contribute - ```sh - pnpm ci:check - pnpm test:ci - pnpm vite build - ``` +A succinct, clearly written issue describing the problem your facing and your desired behavior is worth its weight in gold. -- If you changed the website under `web/`, also run: +This is much easier for me to review than a PR. If its something that I think a coding agent can easily build, I'll have my own agent build it right away. If it's something bigger, I'll add it to the roadmap. - ```sh - pnpm --dir web install --frozen-lockfile - pnpm --dir web run types:check - pnpm --dir web run build - ``` +### Can I still make PRs? + +Yup! I just won't merge them right now. But, making a PR can be a good way to improve the quality of your issue. I'm much more likely to prioritize implementing something myself if you've already created a proof of concept for an integration or built a great UI for me to take inspiration from. + +Videos demoing the feature also help a lot here too since its a sign that the PR wasn't just made by Claude and never tested. + +### /simple-issue-description + +For ease of review, I would appreciate if you used the `/simple-issue-description` to refine your issue. I'm hoping that everything being written in the same voice and format will make it easier to understand issues without a lot of back and forth. + +Install it with: + +```sh +npx skills add every-app/open-seo --skill simple-issue-description +``` + +See [Set up OpenSEO Agent Skills](https://openseo.so/docs/skills/setup) for other install options. + +Here is what we're aiming for with `/simple-issue-description`: + +- There is sufficient detail in the issue. + - What is the problem you're facing? + - What is the full user experience for the feature you're proposing? +- Succinct i.e. not default Claude output. + - I have an `/explain-simply` skill I use all the time which inspired `/simple-issue-description` + - I can't understand the default Claude / Codex output at this point. + +### Our Roadmap + +Here is a link to our Roadmap: http://openseo.so/roadmap + +These are planned features and improvements. If you'd like to create an issue and give your thoughts on what would make these features great, I'm all ears! + +## Wrapping Up + +I know that this may be disappointing for some people. I hope that in 6 months, we have some awesome review process that alleviates my concerns leading to current process. + +If you would like to be more involved though, the best way is to [Join our Discord](https://discord.com/invite/c9uGs3cFXr) : + +- Help others when they ask questions +- Share your experiences doing SEO +- Share things you learned while building your fork