Team conventions

Why this matters

Every team has rules, most of them written down somewhere in the repository, and almost nobody tells a new person where. Reading four files on your first day makes the difference between a first merge request that sails through and one that comes back with six comments about formatting.

The files, and what each governs

Read the first four before your first change. It takes ten minutes and it is the single highest-value thing a new contributor can do.

CONTRIBUTING.md

The one file worth reading in full. A good one answers:

• Which branch to start from, and how branches are named.
• How commit messages should look.
• What a merge request must contain, and how many approvals it needs.
• How to run the tests and the linters locally.
• Who to ask when stuck.

If it does not exist, the conventions still do; they are just unwritten, and you will find them in review. Writing the file afterwards, from what you learned, is a genuinely welcome first contribution.

Commit message conventions

Many teams use conventional commits, which is a prefix on the subject line:

docs: add Windows steps to installation guide (#12)
fix: handle trails with no distance (#15)
feat: add a difficulty filter (#21)
chore: update the CI image to python 3.12
refactor: split the parser into two functions
test: cover the empty-distance case

The prefixes are not decoration: tooling reads them to generate changelogs and to decide version bumps, and feat!: or a BREAKING CHANGE: footer signals a major version. Even without tooling, they make git log --oneline scannable.

The rest of the message follows the ordinary rules (lesson 5.4): imperative mood, under about fifty characters for the subject, a blank line, then the why.

CODEOWNERS

A file mapping paths to people or teams, which the platform uses to request reviews automatically:

*                     @northwind-trails/engineering
/docs/                @northwind-trails/docs
*.md                  @northwind-trails/docs
/CHANGELOG.md         @northwind-trails/docs @dev

The last matching rule wins, which is the opposite of what most people expect. If you are the person who should see documentation changes, ask to be added: it turns "remember to ask Ana" into an automatic review request (lesson 9.5).

Definition of done

Many teams have one, and it is worth asking for explicitly, because "done" is where most disagreements about scope actually live. A typical one:

1. The change works and is covered by a test, where a test makes sense.
2. The documentation is updated in the same merge request.
3. The changelog has an entry.
4. The pipeline is green.
5. It has been reviewed and approved.
6. The issue is linked and closes on merge.

Notice how much of that list is documentation and process rather than code. On many teams the person who notices items 2, 3 and 6 are missing is exactly the sort of contributor this course is for.

The unwritten rules

Some conventions are never written down. Three ways to find them without asking twice:

• Read the last ten merged merge requests. Their titles, descriptions and review comments show the real standard, including how much detail is expected.
• Read git log --oneline -30. The commit message style is visible immediately, and it is more reliable than the documented one.
• Ask once, in the issue or the merge request, so the answer is recorded where the next person will find it.

How to do it

$ ls -a
$ cat CONTRIBUTING.md
$ git log --oneline -20
$ git branch -r

Common mistakes

• Not reading CONTRIBUTING.md. It is written for exactly this moment.
• Following the documented convention when the repository does something else. The repository is the truth; the document may be stale, and fixing it is a good first contribution.
• Deleting a template's headings instead of filling them in.
• Inventing your own commit prefix. Use the project's list.
• Asking in chat, where the answer helps one person once.
• Assuming "done" means the code works. Ask for the definition of done.