teamrepo

A test suite for team systems documentation

Goal

Define a consistent interface for engineering teams' internal documentation. Each team should have a repo and there should be a predictable layout and baseline set of content in each repo.

This should make it easier for new team members & members of other teams to discover basic information such as team charter, repo ownership, and onboarding materials.

Who is this for?

• Managers & team members: makes it easy to keep your team repo consistent with other teams
• Eng ops: gives us a path forward for iterating on/rolling out changes across teams and capturing it in code rather than via people-nagging

Team repo spec

The teamrepo tests ensure that a repo follows this basic structure:

• readme.md: top-level documentation, includes a ## Contents section to hold table of contents (ToC)
• charter.md: team charter
• onboarding/
  • readme.md: includes high-level description and ToC of onboarding files/subdirectories
  • onboarding materials (e.g. tutorials, reading lists) organized as needed
• hiring/
  • readme.md: includes high-level description and ToC of hiring files/subdirectories
  • recruiting materials (e.g. homework assignments, interview questions) organized as needed

In any subdirectory in the repo, there must be a readme.md with a ToC that links to all the files/directories contained within.

Installation & Usage

Command line tool

The teamrepo tool can be used to run the tests against a local repo directory.

$ git clone git@github.com:mapbox/teamrepo.git
Cloning into 'teamrepo'...
$ npm install -g teamrepo/
$ teamrepo geocoding/
TAP version 13
# geocoding team charter
ok 1 geocoding/charter.md should exist and not be empty
...

Ignoring files/subdirectories

Directories and files whose names start with ., e.g. .git, are ignored by default (using the ignore module). If you wish to ignore or unignore specific files, include a file named .teamrepoignore in the root of your repo with a newline-separated list of the file patterns to (un)ignore, e.g.:

# patterns to ignore
ignoreme.md
**/ignoremeanywhere.md
ignorethisdir

# patterns to unignore
!.dontignoreme