docs: add end-to-end collector tutorial and link it from onboarding docs

[snowfox1003]

Summary

Adds docs/Tutorial_building_a_collector.md, a step-by-step guide for creating a collector from scratch (startcollector, AbstractCollector hooks, pytest, YAML/Celery scheduling, deployment). Uses a fictional heartbeat_demo app (local only, not committed) and points to real in-repo examples (cppa_user_tracker, wg21_paper_tracker).
Wires the tutorial into existing docs so new contributors have a clear path:

• CONTRIBUTING.md — “Start here” link before the startcollector checklist
• README.md — step 7 points to tutorial → startcollector → checklist
• Onboarding.md — reading order includes the tutorial (after CONTRIBUTING)
• docs/README.md — topic index entry
• How_to_add_a_collector.md — tutorial link + note on default run_<app>.py layout vs optional collectors.py split
• core/collectors/README.md — walkthrough + checklist links
  Docs-only; no collector code, schedule, or service-layer changes.

Apps touched

• (none — documentation only; core/collectors/README.md updated)

Test plan

• python -m pytest (or scoped: python -m pytest <app>/tests)
• uv run pyright (if typed code changed)
• lint-imports (if imports or cross-app coupling changed)
• App command smoke-tested (if collector/command changed):

Manual:

• Spot-check links in Tutorial_building_a_collector.md, CONTRIBUTING.md, README.md, Onboarding.md, docs/README.md, How_to_add_a_collector.md

Docs / coupling

• cross-app-dependencies.md updated (if FKs or cross-app imports changed)
• python scripts/generate_service_docs.py run (if services.py or core/protocols.py changed)
• App README or docs/ updated (if behavior or ops changed)

---

Closes #231

Summary by CodeRabbit

• Documentation
  • Added a comprehensive step‑by‑step tutorial for building collectors with a worked example, testing guidance, scheduling/production notes, and a copy‑paste checklist.
  • Updated onboarding and docs index to surface the new tutorial and related reference guides.
  • Revised README and contributor guidance to direct authors to the tutorial and the contributor checklist when adding new collectors.

[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: cbb6d6d1-7740-4cc3-94da-8b1205bad83d

📥 Commits

Reviewing files that changed from the base of the PR and between 9d2a2d0 and 43692d0.

📒 Files selected for processing (4)

• CONTRIBUTING.md
• core/collectors/README.md
• docs/How_to_add_a_collector.md
• docs/Onboarding.md

💤 Files with no reviewable changes (1)

• core/collectors/README.md

✅ Files skipped from review due to trivial changes (3)

• docs/How_to_add_a_collector.md
• CONTRIBUTING.md
• docs/Onboarding.md

---

📝 Walkthrough

Walkthrough

Adds a new end-to-end tutorial (docs/Tutorial_building_a_collector.md) for scaffolding and implementing Django collectors; updates multiple documentation entry points to reference the tutorial; and updates the generated package version string.

Changes

Collector Tutorial and Documentation Updates

Layer / File(s)	Summary
Core collector building tutorial docs/Tutorial_building_a_collector.md	New 478-line tutorial covering framing/prereqs, startcollector scaffolding and generated files, AbstractCollector/BaseCollectorCommand lifecycle and error taxonomy, evolving the worked heartbeat_demo example (CLI wiring, service-layer writes, validation), pytest testing guidance (service, command integration, collector unit tests), YAML/Celery scheduling with Beat, deployment readiness checklist, and a copy-paste checklist with further reading links.
Documentation navigation and entry-point updates CONTRIBUTING.md, README.md, core/collectors/README.md, docs/How_to_add_a_collector.md, docs/Onboarding.md, docs/README.md	Documentation files updated to add a “Start here” tutorial link, insert the tutorial into onboarding/index entries, clarify startcollector output layout, and adjust contributing/onboarding guidance to reference the walkthrough.
Generated version update core/_version.py	Package version constant updated by setuptools-scm to a new revision/build identifier.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• cppalliance/boost-data-collector#154: Updated onboarding/docs index entries similar to these navigation edits.
• cppalliance/boost-data-collector#179: Related changes to collector creation documentation and skeleton walkthroughs.

Suggested labels

documentation

Suggested reviewers

• wpak-ai

Poem

🐰 I hopped through docs to plant a guiding chart,
A heartbeat_demo to teach the art.
Links woven tidy, checklists set to start,
New collectors find their path, a joyful little part.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly and concisely summarizes the main change: adding an end-to-end collector tutorial and integrating it into onboarding documentation.
Description check	✅ Passed	The description covers summary, apps touched, test plan with checkboxes, and manual verification steps. All required template sections are present and adequately completed.
Linked Issues check	✅ Passed	The PR fulfills all acceptance criteria from issue #231: tutorial covers scaffolding, AbstractCollector hooks, testing, deployment, Celery/YAML scheduling, includes a worked heartbeat_demo example, and mentions cross-app-dependencies.md.
Out of Scope Changes check	✅ Passed	All changes are in-scope documentation: new tutorial, updated references in CONTRIBUTING/README/Onboarding/docs files, and version bump. No unrelated code or app modifications are present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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