docs: add contribution guidelines by TomCC7 · Pull Request #2530 · dimensionalOS/dimos

TomCC7 · 2026-06-19T06:24:18Z

Linked issue or discussion

Linear: DIM-1021
closes #2529

Summary

Adds a concise contribution SOP for community contributors and refines GitHub templates to improve issue/PR scoping.

Changes include:

root CONTRIBUTING.md
updated PR template
expanded bug report template
expanded feature request template

Validation

uv run pre-commit run --files CONTRIBUTING.md .github/pull_request_template.md .github/ISSUE_TEMPLATE/bug_report.yml .github/ISSUE_TEMPLATE/feature_request.yml

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.

AI assistance used? Yes, drafted and edited with an AI coding agent under human direction.

codecov · 2026-06-19T06:31:12Z

❌ 1 Tests Failed:

Tests completed	Failed	Passed	Skipped
2186	1	2185	70

View the full list of 1 ❄️ flaky test(s)

dimos.e2e_tests.test_dimsim_walk_forward::test_walk_forward

Flake rate in main: 33.33% (Passed 12 times, Failed 6 times)

Stack Traces | 205s run time

lcm_spy = <dimos.e2e_tests.lcm_spy.LcmSpy object at 0x72bc7fc3dfd0>
start_blueprint = <function start_blueprint.<locals>.set_name_and_start at 0x72bc7d914b80>
human_input = <function human_input.<locals>.send_human_input at 0x72bc7d916480>
dim_sim = <dimos.e2e_tests.dim_sim_client.DimSimClient object at 0x72bc7f6a3680>

    @pytest.mark.self_hosted_large
    def test_walk_forward(lcm_spy, start_blueprint, human_input, dim_sim) -> None:
        start_blueprint(
            "run",
            "--disable",
            "spatial-memory",
            "--disable",
            "security-module",
            "unitree-go2-agentic",
            simulator="dimsim",
        )
        lcm_spy.save_topic(".../McpClient/on_system_modules/res")
        lcm_spy.wait_for_saved_topic(".../McpClient/on_system_modules/res", timeout=1200.0)
    
        origin_x, origin_y = 1, 2
        dim_sim.set_agent_position(origin_x, origin_y)
    
        human_input("move forward 3 meter")
    
>       lcm_spy.wait_until_odom_position(origin_x + 3, origin_y, threshold=0.4, timeout=120)

dim_sim    = <dimos.e2e_tests.dim_sim_client.DimSimClient object at 0x72bc7f6a3680>
human_input = <function human_input.<locals>.send_human_input at 0x72bc7d916480>
lcm_spy    = <dimos.e2e_tests.lcm_spy.LcmSpy object at 0x72bc7fc3dfd0>
origin_x   = 1
origin_y   = 2
start_blueprint = <function start_blueprint.<locals>.set_name_and_start at 0x72bc7d914b80>

dimos/e2e_tests/test_dimsim_walk_forward.py:37: 
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 
dimos/e2e_tests/lcm_spy.py:182: in wait_until_odom_position
    self.wait_for_message_result(
        predicate  = <function LcmSpy.wait_until_odom_position.<locals>.predicate at 0x72bc7d916200>
        self       = <dimos.e2e_tests.lcm_spy.LcmSpy object at 0x72bc7fc3dfd0>
        threshold  = 0.4
        timeout    = 120
        x          = 4
        y          = 2
dimos/e2e_tests/lcm_spy.py:168: in wait_for_message_result
    self.wait_until(
        event      = <threading.Event at 0x72bc7f6a8980: unset>
        fail_message = 'Failed to get to position x=4, y=2'
        listener   = <function LcmSpy.wait_for_message_result.<locals>.listener at 0x72bc7d9162a0>
        predicate  = <function LcmSpy.wait_until_odom_position.<locals>.predicate at 0x72bc7d916200>
        self       = <dimos.e2e_tests.lcm_spy.LcmSpy object at 0x72bc7fc3dfd0>
        timeout    = 120
        topic      = '/odom#geometry_msgs.PoseStamped'
        type       = <class 'dimos.msgs.geometry_msgs.PoseStamped.PoseStamped'>
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 

self = <dimos.e2e_tests.lcm_spy.LcmSpy object at 0x72bc7fc3dfd0>

    def wait_until(
        self,
        *,
        condition: Callable[[], bool],
        timeout: float,
        error_message: str,
        poll_interval: float = 0.1,
    ) -> None:
        start_time = time.time()
        while time.time() - start_time < timeout:
            if condition():
                return
            time.sleep(poll_interval)
>       raise TimeoutError(error_message)
E       TimeoutError: Failed to get to position x=4, y=2

condition  = <bound method Event.is_set of <threading.Event at 0x72bc7f6a8980: unset>>
error_message = 'Failed to get to position x=4, y=2'
poll_interval = 0.1
self       = <dimos.e2e_tests.lcm_spy.LcmSpy object at 0x72bc7fc3dfd0>
start_time = 1781889409.1562123
timeout    = 120

dimos/e2e_tests/lcm_spy.py:105: TimeoutError

To view more test analytics, go to the Test Analytics Dashboard
_{📋 Got 3 mins? Take this short survey to help us improve Test Analytics.}

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

mustafab0 · 2026-06-19T07:46:01Z

+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.


We should add vibecoded implementations without any discussion or explanation will not be reviewed, due to the shear volume of PR requests daily.

The team cannot keep up. Well scoped PRs should be merged.

We (aiohttp) added some instructions to agents so that they now add to the end of the PR which tool created the PR and which human reviewed it, plus having it open in draft.

End result is that if the PR remains in draft or the comment says "pending human review", we know not to bother looking at the PR and just close it after some inactivity.

mustafab0 · 2026-06-19T07:46:27Z

+
+Choose the path based on the size and risk of the change:
+
+- Small, safe changes can go straight to a pull request.


Should we do a number of line changes as a metric to what defines as Small vs Non Trivial

I think that would be too pedantic? I think the point to do classification here is to encourage communication/transparency. I actually think submitting a plan along with implementation is perfectly fine here as long as the contributor understand that we won't go into the code directly until we agree on the overall plan shape.

mustafab0 · 2026-06-19T07:47:34Z

+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


This is great 👍

I feel like if you're asking an AI agent what issue etc. it was working on, it sounds like you're just running AI agent experiments on our repo...
That's just spam. If we want AI agents automatically fixing issues, we'd just set that up ourselves, right?

this is actually prompt for both agent and human to take responsibility to their PR. similar to what you described in #2530 (comment). Might need better wording

People are going to use llm to generate text irrespective. I think it is futile to police like that.

Instead providing a standard makes things easier for everyone.

Although it is true that we have greptile generate PR summaries and description which is well scoped so we shouldn't need another PR description.

Maybe the only thing a user should provide is a Link to the issue they addressed and instructions on how to test their PR in detail.

Rest Greptile should be able to handle.

People are going to use llm to generate text irrespective. I think it is futile to police like that.

We've banned several users on aio-libs that were clearly just AI bots (with the accounts calling themselves "AI engineers"), and now the level of spam is minimal. So I think it's saved us plenty of time not reviewing stuff that was written and reviewed by nobody. We can generate our own PRs with a bot when we want (which is almost always better quality than these other agents).

paul-nechifor · 2026-06-19T11:04:53Z

-<!-- What you changed and why this approach -->
-<!-- Key design decisions / tradeoffs -->
-<!-- Keep it high-signal; deep planning belongs in the issue. -->
+<!-- What changed and why? Keep this focused; deeper discussion belongs in the linked issue. -->


The reason this has been split into Problem/Solution is because a lot of people submit PRs where they set agents to describe in intimate detail every aspect of what they changes (including how many lines they changed in every file) but never bother to say why we'd want to merge the PR to begin with.

Describing what the issue is is the most important part. The summary is not as important because you can deduce that from the the diff

paul-nechifor · 2026-06-19T11:05:37Z

+<!-- Required for non-trivial changes. Small safe fixes may write "N/A". -->

-Closes DIM-XXX
+Closes #


We decided a while ago that Linear is the primary source, hence why DIM-XXX is used.

Does it get auto-closed on merge though?

But linear is only visible internally right?

Does it get auto-closed on merge though?

@Dreamsorcerer yes. It auto closes it.
It's pretty sweet.

But linear is only visible internally right?
Yes, that's the idea 😅

paul-nechifor · 2026-06-19T11:23:05Z

+If you use an AI coding agent, ask it to explain:
+
+- what files it changed and why


It's unclear what this refers to. Are you saying people should use LLMs to create PR descriptions? I don't like that. It's annoying when someone submits a PR and explains every single change in every file.

Well written code doesn't need that type of explanation. If something complex is added, it probably should be explained in docs/ or in docstrings, not the PR description.

I'd rather have PR descriptions be human written only. Shorter is better. Agents just throw walls of text.

In other words, when someone wants to make a contribution, something motivated him to make that contribution. That should be what's written in the description, in the contributors own words. There's no need for that to be passed through an LLM.

https://github.com/dimensionalOS/dimos/pull/2530/changes#r3443726373

paul-nechifor · 2026-06-19T11:27:52Z

-        ## Logs / screenshots
-
+      label: What happened?
+      description: Describe the bug and its impact.


If you look at the history, we've had this long questionnaires before. That change was reverted into something more direct and freeflowing.

You might want to discuss this with @leshy .

Yeah, these tend to annoy me. There's always cases where the boxes are not relevant. I don't a more structured form as long as nothing is required.

paul-nechifor · 2026-06-19T11:42:26Z


-<!-- oneliner required to run the actual feature -->
-<!-- blueprint for robot changes, benchmarks for transport changes etc -->
+<!-- What checks did you run? Include commands, relevant output, screenshots, or robot/sim notes when useful. -->


The key issue here is that we want human instructions to run the actual feature. In this PR you added this:

uv run pre-commit run --files CONTRIBUTING.md .github/pull_request_template.md .github/ISSUE_TEMPLATE/bug_report.yml .github/ISSUE_TEMPLATE/feature_request.yml

This is not useful. All of that runs in CI so there's no reason to mention it here. This PR doensn't change any functionality, so the section should be blank.

This whole thing was started because we wanted a way for reviewers to be able to validate that the feature worked for them. I.e. manual tests, not automated tests.

For example, if the PR implemented spatial memory, the section should look something like this:

Start the blueprint:

uv run --simulation=dimsim dimos run unitree-go2-agentic

Start the humancli:

uv run dimos run unitree-go2-agentic

Teleop the robot around to the bed room.
Teleop outside the house
Type in humancli: "Go to the bed."
The robot should start moving and go to the bedroom.

The point is to instruct a person how to use the feature, because, for example, I might not know which blueprint I'm supposed to use. It allows a reviewer to easily validate that the feature was implemented correctly. Without this section, a reviewer would have to deeply inspect the code to figure out all of this.

Dreamsorcerer · 2026-06-19T13:54:14Z

+- 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`.


On aiohttp, we try to clarify that these are designed for human contributors to learn from, not suitable for AI agents to churn through. Probably makes no difference though..

docs: add contribution guidelines

d90e28a

TomCC7 commented Jun 19, 2026

View reviewed changes

docs: simplify contribution templates

a72501b

TomCC7 commented Jun 19, 2026

View reviewed changes

Comment thread CONTRIBUTING.md Outdated

docs: clarify contribution entry points

d44f733

TomCC7 marked this pull request as ready for review June 19, 2026 06:44

TomCC7 requested review from Dreamsorcerer, leshy, mustafab0, paul-nechifor and spomichter as code owners June 19, 2026 06:44

This comment was marked as resolved.

Sign in to view

greptile-apps Bot reviewed Jun 19, 2026

View reviewed changes

Comment thread .github/ISSUE_TEMPLATE/bug_report.yml Outdated

Comment thread .github/ISSUE_TEMPLATE/bug_report.yml Outdated

Update .github/ISSUE_TEMPLATE/bug_report.yml

cc48925

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

TomCC7 commented Jun 19, 2026

View reviewed changes

Comment thread .github/ISSUE_TEMPLATE/bug_report.yml Outdated

Update .github/ISSUE_TEMPLATE/bug_report.yml

8490c7b

github-actions Bot added the ready-to-merge Required CI checks have passed on this PR label Jun 19, 2026

mustafab0 reviewed Jun 19, 2026

View reviewed changes

paul-nechifor reviewed Jun 19, 2026

View reviewed changes

Comment thread .github/pull_request_template.md Outdated

paul-nechifor reviewed Jun 19, 2026

View reviewed changes

Dreamsorcerer reviewed Jun 19, 2026

View reviewed changes

Comment thread .github/ISSUE_TEMPLATE/bug_report.yml Outdated

Dreamsorcerer reviewed Jun 19, 2026

View reviewed changes

docs: strengthen contribution workflow

35b96ae

github-actions Bot added ready-to-merge Required CI checks have passed on this PR and removed ready-to-merge Required CI checks have passed on this PR labels Jun 19, 2026


		Choose the path based on the size and risk of the change:

		- Small, safe changes can go straight to a pull request.

		If you use an AI coding agent, ask it to explain:

		- what files it changed and why

Conversation

TomCC7 commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Linked issue or discussion

Summary

Validation

Checklist

Uh oh!

codecov Bot commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

❌ 1 Tests Failed:

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TomCC7 Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mustafab0 Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

paul-nechifor Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

TomCC7 commented Jun 19, 2026 •

edited

Loading

codecov Bot commented Jun 19, 2026 •

edited

Loading

TomCC7 Jun 19, 2026 •

edited

Loading

mustafab0 Jun 19, 2026 •

edited

Loading

paul-nechifor Jun 19, 2026 •

edited

Loading