From d90e28a505f7bf2b879447a77f5ae988458ef149 Mon Sep 17 00:00:00 2001 From: cc Date: Thu, 18 Jun 2026 23:23:37 -0700 Subject: [PATCH 1/6] docs: add contribution guidelines --- .github/ISSUE_TEMPLATE/bug_report.yml | 67 ++++++++++++++++------ .github/ISSUE_TEMPLATE/feature_request.yml | 39 +++++++++++-- .github/pull_request_template.md | 25 ++++---- CONTRIBUTING.md | 62 ++++++++++++++++++++ 4 files changed, 161 insertions(+), 32 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 6d45432d50..5e8c4d1fcf 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -3,22 +3,57 @@ description: Report a bug in DimOS labels: ["bug"] body: - type: textarea - id: description + id: what-happened attributes: - label: Description - value: | - ## System - - - ## Robot/Sim/Hardware (including firmware version) - - - ## Steps to reproduce - - ## DimOS version - - - ## Logs / screenshots - + label: What happened? + description: Describe the bug and its impact. + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected behavior + description: What did you expect to happen? + validations: + required: true + - type: textarea + id: reproduce + attributes: + label: Steps to reproduce + description: Include commands, blueprint names, robot/sim setup, and any relevant inputs. + placeholder: | + 1. + 2. + 3. + validations: + required: true + - type: textarea + id: logs + attributes: + label: Logs or screenshots + description: Paste relevant logs, tracebacks, screenshots, or videos. + render: shell + validations: + required: false + - type: textarea + id: environment + attributes: + label: Environment + description: Include OS, Python version, DimOS branch/commit, robot/sim/hardware, and firmware when relevant. + placeholder: | + OS: + Python: + DimOS branch/commit: + Robot/sim/hardware: + validations: + required: true + - type: dropdown + id: willing-to-fix + attributes: + label: Are you willing to help fix this? + options: + - "Yes" + - "No" + - "Maybe" validations: required: true diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 9a1c6ed03f..cf25c8bc69 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -3,10 +3,41 @@ description: Suggest a new feature or improvement for DimOS labels: ["feature"] body: - type: textarea - id: description + id: motivation attributes: - label: Description - description: What do you want and why? - + label: Problem or motivation + description: What problem would this solve? Who needs it? + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed contribution + description: What behavior, API, module, skill, blueprint, or documentation change do you propose? + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: What other approaches did you consider? + validations: + required: false + - type: input + id: affected-area + attributes: + label: Affected area + description: Which part of DimOS would this touch? + placeholder: e.g. modules, streams, blueprints, agents, skills, navigation, perception, docs + validations: + required: true + - type: dropdown + id: willing-to-implement + attributes: + label: Are you willing to implement this? + options: + - "Yes" + - "No" + - "Maybe" validations: required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 61ffabc38d..55caf499a2 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,21 +1,22 @@ -## Problem +## Linked issue or discussion - - + -Closes DIM-XXX +Closes # -## Solution +## Summary - - - + -## How to Test +## Validation - - + -## Contributor License Agreement +## Checklist +- [ ] This PR is scoped to one issue or clearly stated problem. +- [ ] I have run the relevant checks for the files I changed. +- [ ] I have reviewed and understand the changes in this PR. - [ ] I have read and approved the [CLA](https://github.com/dimensionalOS/dimos/blob/main/CLA.md). + +AI assistance used? diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..7ce912e5bb --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,62 @@ +# Contributing to DimOS + +DimOS welcomes community contributions. This guide explains how to start work, communicate scope, and submit a pull request that maintainers can review efficiently. + +## Start in the right place + +Use GitHub for public contribution coordination. + +- For small, safe changes, you may open a pull request directly. Examples include typo fixes, broken links, small documentation clarifications, and clearly isolated bug fixes. +- For non-trivial changes, open or comment on a GitHub issue before implementation. This includes new features, behavior changes, new modules, new skills, new blueprints, dependency changes, and larger documentation changes. +- For core architecture changes, start with a GitHub issue or discussion and wait for maintainer guidance before implementation. + +New contributors can start with issues labeled `good first issue`. + +## Changes that need discussion first + +Please do not open unsolicited pull requests for: + +- large rewrites or broad refactors +- new framework abstractions or public APIs +- new robot or platform support +- major dependency changes +- changes to core module, stream, transport, blueprint, or agent architecture + +These changes may still be useful, but they need agreement on direction before code review. + +## Pull request shape + +Before opening a pull request, make sure it is: + +- scoped to one issue or clearly stated problem +- linked to the relevant GitHub issue or discussion when required +- focused, without unrelated cleanup or formatting changes +- clear about what changed and why +- validated with the checks relevant to the files you changed + +The pull request template asks for the details maintainers need. Keep deeper design discussion in the issue or discussion that the PR links to. + +## Validation + +Run the relevant local checks before submitting. Pre-commit and CI will also guide you toward the required checks for the files you changed. + +For test guidance, see [docs/development/testing.md](docs/development/testing.md). + +## AI-assisted contributions + +AI-assisted contributions are welcome when the human contributor owns the result. + +If AI materially helped prepare a pull request, disclose that in the PR. You are responsible for understanding the change, checking it against the agreed scope, and running relevant validation. + +If you use an AI coding agent, ask it to explain: + +- what files it changed and why +- which issue or discussion scope it followed +- what checks it ran and the results +- any risks, assumptions, or follow-up work + +Review that explanation before submitting the PR. + +## Contributor License Agreement + +Before submitting a pull request, read and approve the [Contributor License Agreement](CLA.md). From a72501bedcf5199b0e2250c3a58ebaff18e1004d Mon Sep 17 00:00:00 2001 From: cc Date: Thu, 18 Jun 2026 23:35:53 -0700 Subject: [PATCH 2/6] docs: simplify contribution templates --- .github/ISSUE_TEMPLATE/feature_request.yml | 36 +++++++--------------- .github/pull_request_template.md | 4 +-- CONTRIBUTING.md | 22 ++++--------- 3 files changed, 19 insertions(+), 43 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index cf25c8bc69..db3d88d7d3 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -6,38 +6,24 @@ body: id: motivation attributes: label: Problem or motivation - description: What problem would this solve? Who needs it? + description: What do you want and why? validations: required: true - type: textarea - id: proposal + id: request-or-plan attributes: - label: Proposed contribution - description: What behavior, API, module, skill, blueprint, or documentation change do you propose? - validations: - required: true - - type: textarea - id: alternatives - attributes: - label: Alternatives considered - description: What other approaches did you consider? + label: Request or implementation plan + description: If this is a request, describe the desired behavior. If you plan to implement it, describe your proposed approach. validations: required: false - - type: input - id: affected-area - attributes: - label: Affected area - description: Which part of DimOS would this touch? - placeholder: e.g. modules, streams, blueprints, agents, skills, navigation, perception, docs - validations: - required: true - type: dropdown - id: willing-to-implement + id: contribution-intent attributes: - label: Are you willing to implement this? + label: How would you like to help? options: - - "Yes" - - "No" - - "Maybe" + - "I can implement this" + - "I can test or review this" + - "Request only" + - "Not sure yet" validations: - required: true + required: false diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 55caf499a2..90ba13443d 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -14,9 +14,9 @@ Closes # ## Checklist +- [ ] I linked the relevant issue or discussion, or this is a small safe fix. - [ ] This PR is scoped to one issue or clearly stated problem. - [ ] I have run the relevant checks for the files I changed. - [ ] I have reviewed and understand the changes in this PR. +- [ ] I disclosed AI assistance if it materially helped prepare this PR. - [ ] I have read and approved the [CLA](https://github.com/dimensionalOS/dimos/blob/main/CLA.md). - -AI assistance used? diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7ce912e5bb..b06f90c73d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,29 +2,19 @@ DimOS welcomes community contributions. This guide explains how to start work, communicate scope, and submit a pull request that maintainers can review efficiently. -## Start in the right place +## Before you code Use GitHub for public contribution coordination. -- For small, safe changes, you may open a pull request directly. Examples include typo fixes, broken links, small documentation clarifications, and clearly isolated bug fixes. -- For non-trivial changes, open or comment on a GitHub issue before implementation. This includes new features, behavior changes, new modules, new skills, new blueprints, dependency changes, and larger documentation changes. -- For core architecture changes, start with a GitHub issue or discussion and wait for maintainer guidance before implementation. +- Small, safe changes can go straight to a pull request. +- Non-trivial changes should start with a GitHub issue. +- Core architecture changes should start with a GitHub issue or discussion before implementation. New contributors can start with issues labeled `good first issue`. -## Changes that need discussion first +Core architecture includes modules, streams, transports, blueprints, agents, public APIs, robot/platform support, and major dependency changes. -Please do not open unsolicited pull requests for: - -- large rewrites or broad refactors -- new framework abstractions or public APIs -- new robot or platform support -- major dependency changes -- changes to core module, stream, transport, blueprint, or agent architecture - -These changes may still be useful, but they need agreement on direction before code review. - -## Pull request shape +## Pull requests Before opening a pull request, make sure it is: From d44f733214d623848ed23134930fc77e5aab5815 Mon Sep 17 00:00:00 2001 From: cc Date: Thu, 18 Jun 2026 23:40:30 -0700 Subject: [PATCH 3/6] docs: clarify contribution entry points --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b06f90c73d..e8ba927445 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,7 +4,7 @@ DimOS welcomes community contributions. This guide explains how to start work, c ## Before you code -Use GitHub for public contribution coordination. +Choose the path based on the size and risk of the change: - Small, safe changes can go straight to a pull request. - Non-trivial changes should start with a GitHub issue. From cc4892525802c01a9df58cbb422c1faf0652a542 Mon Sep 17 00:00:00 2001 From: cc <55869557+TomCC7@users.noreply.github.com> Date: Thu, 18 Jun 2026 23:57:28 -0700 Subject: [PATCH 4/6] Update .github/ISSUE_TEMPLATE/bug_report.yml Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> --- .github/ISSUE_TEMPLATE/bug_report.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 5e8c4d1fcf..564af411d0 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -32,7 +32,6 @@ body: attributes: label: Logs or screenshots description: Paste relevant logs, tracebacks, screenshots, or videos. - render: shell validations: required: false - type: textarea From 8490c7bf359099832406b77344e57eb66b14b97b Mon Sep 17 00:00:00 2001 From: cc <55869557+TomCC7@users.noreply.github.com> Date: Thu, 18 Jun 2026 23:59:26 -0700 Subject: [PATCH 5/6] Update .github/ISSUE_TEMPLATE/bug_report.yml --- .github/ISSUE_TEMPLATE/bug_report.yml | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 564af411d0..923f9f32fe 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -46,13 +46,3 @@ body: Robot/sim/hardware: validations: required: true - - type: dropdown - id: willing-to-fix - attributes: - label: Are you willing to help fix this? - options: - - "Yes" - - "No" - - "Maybe" - validations: - required: true From 35b96ae149edfba01dd1e4546b37e010b8f7f7b7 Mon Sep 17 00:00:00 2001 From: cc Date: Fri, 19 Jun 2026 09:57:02 -0700 Subject: [PATCH 6/6] docs: strengthen contribution workflow --- .github/ISSUE_TEMPLATE/bug_report.yml | 56 +++++++-------------------- .github/pull_request_template.md | 22 +++++++---- CONTRIBUTING.md | 21 +++++----- 3 files changed, 41 insertions(+), 58 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 923f9f32fe..74d00712a3 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -1,48 +1,22 @@ name: Bug Report description: Report a bug in DimOS -labels: ["bug"] +type: Bug body: - type: textarea - id: what-happened + id: description attributes: - label: What happened? - description: Describe the bug and its impact. - validations: - required: true - - type: textarea - id: expected - attributes: - label: Expected behavior - description: What did you expect to happen? - validations: - required: true - - type: textarea - id: reproduce - attributes: - label: Steps to reproduce - description: Include commands, blueprint names, robot/sim setup, and any relevant inputs. - placeholder: | - 1. - 2. - 3. - validations: - required: true - - type: textarea - id: logs - attributes: - label: Logs or screenshots - description: Paste relevant logs, tracebacks, screenshots, or videos. + label: Description + description: Describe what happened and include any details that seem relevant. + value: | + ## What happened? + + ## What did you expect? + + ## Steps to reproduce + + ## Environment + + + ## Logs / screenshots validations: required: false - - type: textarea - id: environment - attributes: - label: Environment - description: Include OS, Python version, DimOS branch/commit, robot/sim/hardware, and firmware when relevant. - placeholder: | - OS: - Python: - DimOS branch/commit: - Robot/sim/hardware: - validations: - required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 90ba13443d..0aefbe1c69 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,20 +1,28 @@ -## Linked issue or discussion +## Contribution path - + + +- [ ] Small, safe change that does not need a tracking issue +- [ ] Linked issue/discussion: DIM-XXX / #XXX / URL + +## Problem + + Closes # -## Summary +## Solution - + -## Validation +## How to Test - + ## Checklist -- [ ] I linked the relevant issue or discussion, or this is a small safe fix. +- [ ] I followed the contribution path above. - [ ] This PR is scoped to one issue or clearly stated problem. - [ ] I have run the relevant checks for the files I changed. - [ ] I have reviewed and understand the changes in this PR. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e8ba927445..74199545e9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,10 +4,11 @@ DimOS welcomes community contributions. This guide explains how to start work, c ## Before you code -Choose the path based on the size and risk of the change: +Choose the path that keeps discussion focused: - Small, safe changes can go straight to a pull request. -- Non-trivial changes should start with a GitHub issue. +- Non-trivial changes should start with a GitHub issue before implementation. +- If you already have a draft pull request for a non-trivial change, open or link an issue for the design discussion and keep the PR focused on the implementation. - Core architecture changes should start with a GitHub issue or discussion before implementation. New contributors can start with issues labeled `good first issue`. @@ -19,12 +20,12 @@ Core architecture includes modules, streams, transports, blueprints, agents, pub Before opening a pull request, make sure it is: - scoped to one issue or clearly stated problem -- linked to the relevant GitHub issue or discussion when required +- linked to the relevant issue or discussion, unless it is a small, safe change - focused, without unrelated cleanup or formatting changes - clear about what changed and why - validated with the checks relevant to the files you changed -The pull request template asks for the details maintainers need. Keep deeper design discussion in the issue or discussion that the PR links to. +The pull request template asks for the details maintainers need. Keep deeper design discussion in the issue or discussion that the PR links to, not in the PR thread. ## Validation @@ -38,14 +39,14 @@ AI-assisted contributions are welcome when the human contributor owns the result If AI materially helped prepare a pull request, disclose that in the PR. You are responsible for understanding the change, checking it against the agreed scope, and running relevant validation. -If you use an AI coding agent, ask it to explain: +If you use an AI coding agent, review its work before submitting. Do not submit an agent-generated PR that you cannot explain yourself. If the PR is not ready for human review, keep it as a draft. -- what files it changed and why -- which issue or discussion scope it followed -- what checks it ran and the results -- any risks, assumptions, or follow-up work +Before submitting, make sure you can explain in your own words: -Review that explanation before submitting the PR. +- what changed and why +- which issue or discussion scope the PR follows +- what checks you ran and the results +- any risks, assumptions, or follow-up work ## Contributor License Agreement