Your First Contribution

You have the platform running locally and you have read the relevant principle pages. Your first change is a chance to learn the tooling and the review culture, not to design a system. Pick something bounded.

Good candidates for a first PR

• Fix a typo or broken link in the docs. The docs site lives in services/wordloop-docs. Edit an MDX file, rebuild locally, open a PR.
• Add a missing Vale word to our style dictionary when linting flags a legitimate term. This teaches you the quality-governance workflow.
• Tighten an existing test against a real behaviour it does not yet cover. Real bugs fall out of this kind of reading; fabricating new features does not.
• Improve a runbook after you follow it and find a step that is unclear.

The mechanics

1. Branch. git checkout -b your-name/short-description from main. Keep names short and descriptive.
2. Make the change. Small and focused. If you find yourself fixing two things at once, split into two PRs.
3. Run the relevant tests. Use ./dev test <service> for unit tests and ./dev test system for cross-service integration. See Run Tests.
4. Lint your work. ./dev lint all covers Go, Python, and TypeScript; for docs changes run Vale if configured.
5. Commit. Write a commit message that explains why the change is needed, not just what changed. Our history is a long-term artefact.
6. Open a PR. Include a description of the change, the reasoning, a test plan, and links to any related issues or decision records.
7. Respond to review. Reviewers may push back on naming, structure, or scope. Treat review comments as invitations to improve the change, not as attacks.
8. Merge when green. CI must pass; a reviewer must approve.

After merge

Watch the deploy. Our CI/CD pipeline builds a Docker image, pushes it to Artifact Registry, and deploys to Cloud Run. If anything breaks in production, the on-call engineer will page — you may be asked to revert quickly. That is normal; it means the feedback loop is working.

What to read next

• Guides — task-oriented how-tos for the common operations.
• Engineering Principles — the stance behind the code you are about to touch.
• Reference / CLI — every ./dev command in one table.