docs: clarify development setup and package-source checks

[JMartinezRuiz]

Description

Clarifies contributor docs for local server/package work and for reproducing Unity package-source issues.

Type of Change

Documentation update.

Changes Made

• Add a short repo map to the development guide.
• Document the local server setup and common Python test commands.
• Explain when to check Packages/packages-lock.json, since Unity may resolve a Git package to a specific commit even when manifest.json uses a branch name.
• Add notes for local Unity package work, tool/resource changes, compatibility checks, and common development failures.
• Update the PR template to ask for Unity version, package source, resolved commit hash from Packages/packages-lock.json, and the relevant test coverage.
• Replace the stale tools/UPDATE_DOCS.md reference with manual review wording; the repo currently has tools/UPDATE_DOCS_PROMPT.md.

Compatibility / Package Source

• Unity version(s) tested: Not applicable; documentation/template-only change.
• Package source used: local checkout of CoplayDev/unity-mcp#beta.
• Resolved commit hash from Packages/packages-lock.json (if using a Git package URL): Not applicable.

Testing/Screenshots/Recordings

Runtime/package tests were not run because this only changes contributor documentation and the PR template.

Validation performed:

• git diff --check

Documentation Updates

• No tools or resources were added, removed, or modified.
• Developer docs and the PR template were updated manually.

Related Issues

None

Additional Notes

This intentionally leaves workflow changes out of scope; the PR only updates contributor-facing documentation and the PR template.

Summary by CodeRabbit

• Documentation
  • Expanded developer contribution and local development guides with PR rules, package/source guidance, CI-matching local server setup, and refined testing instructions.
  • Added tool development & resource workflow, compatibility notes, and a troubleshooting checklist for common development issues.
  • Revised pull-request template to structured checklists and added a compatibility/package-source section.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c4d32283-c4ab-4e73-9498-fd30c0f5568e

📥 Commits

Reviewing files that changed from the base of the PR and between 905fe15 and b90b811.

📒 Files selected for processing (1)

• docs/development/README-DEV.md

---

📝 Walkthrough

Walkthrough

Updates to the repository's developer-facing materials: the GitHub PR template and the developer README. The PR template gains structured checklists (including package/source fields) and revised testing/documentation prompts. The README expands local setup, package-source guidance, tool/resource authoring, testing examples, compatibility notes, and troubleshooting steps.

Changes

Developer docs and PR template

Layer / File(s)	Summary
PR Template Structure .github/pull_request_template.md	Converted "Type of Change" into checkbox checklist; added "Compatibility / Package Source" checklist for Unity version(s), package source, and optional resolved lockfile commit; replaced testing and documentation checklist items with structured checkboxes and a "manual review of the generated changes" instruction.
Contributing Rules & Local Dev Setup docs/development/README-DEV.md (lines 12–46)	Clarified PR scope rules; added required bug-fix metadata (tested Unity versions, package source, lockfile commit hash for Git URLs, commands/tests); added CI-aligned Python server setup steps (uv sync, editable dev install, default pytest run).
Package Source Guidance & Tools Authoring docs/development/README-DEV.md (lines 72–118)	Recommend using "Local workspace" for package testing; warn against editing Unity package cache; add lockfile/manifest debugging tips and example resolved git lock entry; new "Adding or Changing Tools and Resources" section describing C# vs Python split, required Unity/server decorators, long-running tool guidance, server tool groups, and docs/metadata update workflow.
Testing, Unity Tests & Troubleshooting docs/development/README-DEV.md (lines 179–240)	Expanded Python pytest invocation examples; clarified Unity C# test project's role for import/compile checks; added "Compatibility Notes" and a troubleshooting checklist (stale git packages, Safe Mode, server-change pickup, manage_tools(action="sync"), and MCP instance targeting).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• CoplayDev/unity-mcp#209: Related developer docs and tooling changes (mcp_source.py utility, README guidance) and overlaps in developer workflow updates.

Poem

🐰 Checklists lined up, and guides all in view,
I hop through the docs to show what is new,
From setup to tools, tests tidy and bright,
Troubleshooting tips to set things right,
Developers leap—PRs now feel light! 🥕✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: clarifying development setup guidance and package-source checks in the documentation.
Description check	✅ Passed	The description comprehensively follows the template with all required sections completed, including clear explanations of changes, proper type classification, and appropriate context.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

.github/pull_request_template.md (1)

20-28: ⚡ Quick win

Tighten checklist wording for traceability.

At Line 20 and Line 28, making the source of truth explicit and requiring a brief N/A rationale will reduce review back-and-forth.

Suggested wording update

- - Resolved package hash, if using a Git package URL:
+ - Resolved commit hash from `Packages/packages-lock.json` (if using a Git package URL):

- - [ ] Not applicable
+ - [ ] Not applicable (explain why in Additional Notes)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.github/pull_request_template.md around lines 20 - 28, Update the pull
request checklist wording to make the source-of-truth explicit and require a
brief rationale when marking items not applicable: change the "Resolved package
hash, if using a Git package URL:" line to explicitly ask for the exact
commit/tag/hash used (e.g., "Resolved package hash (if using a Git package URL):
specify commit/tag/hash"), and change the "Not applicable" checkbox to "Not
applicable — provide brief reason" (or similar) so reviewers must include a
short N/A rationale for any skipped checks; apply these text edits in the
checklist section that contains the Python/Unity test and package checks.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In @.github/pull_request_template.md:
- Around line 20-28: Update the pull request checklist wording to make the
source-of-truth explicit and require a brief rationale when marking items not
applicable: change the "Resolved package hash, if using a Git package URL:" line
to explicitly ask for the exact commit/tag/hash used (e.g., "Resolved package
hash (if using a Git package URL): specify commit/tag/hash"), and change the
"Not applicable" checkbox to "Not applicable — provide brief reason" (or
similar) so reviewers must include a short N/A rationale for any skipped checks;
apply these text edits in the checklist section that contains the Python/Unity
test and package checks.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: bf568423-d281-4605-9d9b-1d00953bfdb0

📥 Commits

Reviewing files that changed from the base of the PR and between 37ef016 and 800b30b.

📒 Files selected for processing (2)

• .github/pull_request_template.md
• docs/development/README-DEV.md

[JMartinezRuiz]

Updated the PR template wording based on the review suggestion: the package source field now points to Packages/packages-lock.json, and the Not applicable test option asks for a brief reason. Keeping the PR documentation-only.

[Scriptwonder]

Thanks for the PR! Will merge it rn