Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 11 additions & 23 deletions docs/adr/0001-project-marks-single-gold-inner.md
Original file line number Diff line number Diff line change
@@ -1,23 +1,11 @@
# Project marks are two-colour, differentiated by symbol not colour

**Decision:** Every per-project mark uses the constant green+gold snake frame with a single **gold**
inner symbol. Projects are told apart by the *shape* of the inner symbol, never by colour. There is
no per-family accent hue.

While designing the per-project system we evaluated giving each of the four families its own accent
colour for the inner symbol — a "Heritage" palette (dependency-injection = terracotta, templates =
slate blue, microservices = plum, utilities = teal) and a brighter "Vivid" alternative. The research
on comparable systems (JetBrains, Adobe, Astral) recommends two discriminators, shape **and**
colour — but only because those marks must survive favicon sizes. Our project marks are
large-format only; the org mark remains every repo's favicon.

Rendered side by side, the per-family accent made each mark a **three-colour** object (green frame +
gold frame + accent inner), which read as busy and diluted the org identity. Since favicon-size
legibility is explicitly a non-goal, the second discriminator buys little. A single gold inner keeps
every mark unmistakably part of one family, matches the brand palette exactly, and means a new repo
needs only a new *shape*, not a new colour to keep harmonious. Templates get no symbol at all — they
reuse the org chevron.

**Revisit trigger:** the org needs these marks at favicon scale, so shape alone no longer
disambiguates; or a family grows large enough that a colour band materially helps wayfinding on the
org site.
# Project marks are two-colour, differentiated by symbol, not colour

Every project mark is the constant snake frame plus a single gold inner symbol, so repos are told
apart by the shape of that symbol and never by a hue of their own. Per-family accent palettes were
drawn and rejected: research on comparable systems recommends two discriminators, shape and colour,
but only because those marks must survive favicon sizes, and ours are large-format only since the
org mark stays every repo's favicon. Side by side the accent made each mark a three-colour object
that read as busy and diluted the org identity, while one gold inner keeps the family coherent and
means a new repo needs only a new shape. The two templates get no symbol at all and reuse the org
chevron. `ALLOWED_COLORS` in `projects.py` holds the line; the pytest bars' four-step gold ramp is
its one sanctioned exception.
43 changes: 10 additions & 33 deletions docs/adr/0002-discussions-is-the-only-owned-channel.md
Original file line number Diff line number Diff line change
@@ -1,35 +1,12 @@
# GitHub Discussions is the org's only owned channel

**Decision:** Discussions is the org's sole owned support and feedback surface — org-level at
`/orgs/modern-python/discussions` (backed by this repo, and where `SUPPORT.md` routes every
project's users), plus per-repo tabs on the handful of repos with traffic to fill them. No Discord
server, no Telegram group, and no per-repo tab enabled org-wide. When an *answerable* question
arrives by any other route, it gets pushed to Discussions — "ask there so the next person finds it".

Chat rooms were the obvious alternative and are the one most often asked for. The durable-record
argument is the load-bearing reason against opening them now: a chat answer is ephemeral, while a
Discussions answer is searchable and Google-indexed, so it compounds — it also serves everyone who
later hits the same error. Async also suits a solo maintainer in one timezone.

The stronger reason is the empty-room threshold. A young project's scarcest resource is the
attention needed to seed a room, and an empty room is worse than no room: a visitor who lands on
"3 members, last message 2 weeks ago" gets a worse signal than from a clean Discussions tab. The same
arithmetic rejects enabling Discussions per-repo across all 28 repos — 20-odd empty tabs read as a
dead org. The standing principle is to **borrow audiences before building our own**: participate
where Python users already are rather than standing up rooms we cannot fill.

If rooms ever open, the scope is one org-wide room per platform, never per-repo. The whole stack
shares one community, and the only rationale that keeps two rooms coherent rather than fragmenting a
small one is a language/geo split (Russian-speaking Telegram, English/global Discord).

**Borrowing in practice:** a link back to our own pages is conditional, not standing. Link only
where the linked page actually answers the question at hand (a docs page, or an existing Discussion),
and never as a bare repo drop. The rejected alternative was a mandatory backlink on every reply: that
turns participation into the drive-by self-promotion HN, Lobsters and r/Python each punish, and costs
more standing than the referrals are worth. The obligation that *is* standing runs the other way,
when a question answered in someone else's venue exposes a gap in our docs, that gap becomes an issue
here.

**Revisit trigger:** launch week (the work is tracked in modern-python/.github#58). Rooms open *during* it, not before — launch traffic is what seeds
them past the empty-room threshold. If a room is still inactive 30 days post-launch, fold it back
into Discussions rather than keeping a dead room linked.
GitHub Discussions, org-level at `/orgs/modern-python/discussions` and backed by this repo, is the
only community surface the org runs; `SUPPORT.md` routes every project's users there, and per-repo
tabs stay off except where a repo has traffic to fill one. A Discord server or Telegram group is the
alternative asked for most often, rejected on the empty-room threshold rather than on the durability
of a searchable answer: the scarcest resource is the attention needed to seed a room, and "3
members, last message 2 weeks ago" is a worse signal than a clean Discussions tab. The same
arithmetic rejects enabling Discussions across all 28 repos. The standing principle is to borrow
audiences before building our own, linking back only where the linked page answers the question at
hand, never as a bare repo drop. If rooms ever open they open during launch week, one org-wide room
per platform, never per-repo.
21 changes: 9 additions & 12 deletions docs/adr/0003-flask-horn-historical-artwork-grant.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,11 @@
# The `modern-di-flask` horn is drawn from Flask's own logo path

**Decision:** Two project marks are built from a partner's literal logo path, recoloured into our
palette: `modern-di-faststream` (FastStream's) and `modern-di-flask` (Flask's horn). Every other
integration cue is a redrawn evocation or, where there was nothing to redraw from, an invention.

Flask is the one that needs a record. The permission we rely on is the **Flask Artwork License**,
which explicitly allowed the logo "or a modified version" to be used to refer to the project. That
license was dropped from the Pallets repo after Flask 1.0 and nothing replaced it, so today's Flask
assets ship with no stated terms at all. The grant is historical, but it was explicit at the time we
took it, and it is why the horn is a recolour rather than an evocation like its siblings.

**Revisit trigger:** Pallets publishes restrictive artwork terms, or asks. The horn is one function
in `symbols.py` to redraw.
Two project marks are a partner's literal logo path recoloured into our palette, FastStream's mark
and Flask's drinking horn; every other integration cue is a redrawn evocation or, where there was
nothing to redraw from, an invention. Flask is the one that needs a record. The permission relied on
is the Flask Artwork License, which explicitly allowed the logo "or a modified version" to be used
to refer to the project. Pallets dropped that license from its repo after Flask 1.0 and replaced it
with nothing, so today's Flask assets ship with no stated terms at all. The grant is historical, but
it was explicit when the path was taken, and it is why this mark is a recolour rather than an
evocation like its siblings. If Pallets publishes restrictive terms or asks, `flask_horn` in
`symbols.py` is one function to redraw.
Loading