Contributing

How to contribute to this repo. Short version: propose changes as pull requests. Comments are fine; contributions are better.

Why pull requests over comments

A comment says “I think this could be different.” A pull request says “here’s what it would look like if it were different.”

Comments leave the work of translating an opinion into a change for someone else. Pull requests do the translation up front. The mental model shifts from spectator to contributor. That’s the point.

If you’re new to pull requests on GitHub, use this first one to learn. It’s worth the half hour.

How to propose a change

  1. Fork or branch. If you have write access to this repo, create a branch: your-name/what-you-are-changing. If you don’t, fork the repo.
  2. Make the change. Edit the markdown file. Keep the change focused — one PR per idea.
  3. Open a pull request. Describe what you changed and why. If you’re unsure, open it as a draft and ask for feedback.
  4. Discuss. Reviewers add comments on the proposed change. You respond, revise, or defend.
  5. Merge. Once agreed, the PR gets merged to main. The change is live.

What lives in this repo

  • Strategy and methodology documents (founding brief, tenets, how-cohorts-work)
  • Governance and operating material (governance, roles-and-time, intake)
  • Cohort packages (one directory per cohort)
  • Starter kits and templates
  • Decision records (why we made calls)
  • The FAQ (grows over time)

What doesn’t live in this repo

  • Balsam-confidential commercial information (contracts, pricing for specific partners, individual performance feedback). These live in appropriate internal systems.
  • Customer data, product data samples, or any material under NDA.
  • Personal notes or half-formed thoughts. Drafts are fine; unfinished scratch is better in a personal space.

Authoring conventions

  • Markdown. Plain, readable, minimal styling. Headings for structure.
  • Filenames. Lowercase, hyphenated, .md. Example: how-cohorts-work.md.
  • Voice. Direct. First person plural when representing the CoE. Avoid consulting-speak.
  • Links. Use relative links within the repo: [text](./file.md).
  • Dates. ISO-style where specific (2026-05-01). Month and year where approximate (May 2026).

Decision records (ADRs)

Significant decisions get an ADR in decisions/. Format:

# NNNN — short title

**Date:** YYYY-MM-DD
**Status:** [proposed | accepted | superseded]
**Superseded by:** [optional link]

## Context
[What question needed a decision? What was known at the time?]

## Decision
[What was decided?]

## Reasoning
[Why this option? What trade-offs were considered?]

## Consequences
[What does this change about how we operate?]

Numbered sequentially. New ADRs get the next available number. If a decision is later superseded, mark the old ADR as superseded and link to the new one. Don’t edit history.

Cohort packages

Each cohort gets a directory in cohorts/. Use cohorts/TEMPLATE/ as the starter. Rename to NN-short-name/ where NN is the cohort number (01-product-data, 02-content-production, etc.).

Who can contribute

  • Goose Group operating team: yes, actively.
  • Balsam sponsors (Claire, France): yes, any document.
  • Balsam cohort members: yes, especially their own cohort packages and the FAQ.
  • Balsam employees more broadly: yes, via intake submissions and FAQ additions.
  • Outside Balsam and Goose Group: not during the founding period.

If you’re stuck

Open an issue. Ping Mike or Alex in Slack. This is meant to be used, not to be intimidating.