Skip to content

Commit 54fd3de

Browse files
authored
docs(adr): compress to 3 records in the domain-modeling format (#106)
Rewrite each record as a title plus one paragraph, dropping the **Decision:** lead and the **Revisit trigger:** footer. No record was dropped or merged: all three pass the admission test, so the numbering and every citation are unchanged. - 0001: fold the templates-reuse-the-chevron rule and the ALLOWED_COLORS gate into the paragraph; record the pytest bars' gold ramp as the one sanctioned exception to the single-gold inner. - 0002: keep the empty-room threshold as the load-bearing reason, fold the borrow-audiences principle and the conditional backlink into one clause, and drop the reference to a tracking issue that no longer resolves. - 0003: fold the redraw cost into the paragraph as the boundary of the decision.
1 parent 5ec70f5 commit 54fd3de

3 files changed

Lines changed: 30 additions & 68 deletions

File tree

Lines changed: 11 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,11 @@
1-
# Project marks are two-colour, differentiated by symbol not colour
2-
3-
**Decision:** Every per-project mark uses the constant green+gold snake frame with a single **gold**
4-
inner symbol. Projects are told apart by the *shape* of the inner symbol, never by colour. There is
5-
no per-family accent hue.
6-
7-
While designing the per-project system we evaluated giving each of the four families its own accent
8-
colour for the inner symbol — a "Heritage" palette (dependency-injection = terracotta, templates =
9-
slate blue, microservices = plum, utilities = teal) and a brighter "Vivid" alternative. The research
10-
on comparable systems (JetBrains, Adobe, Astral) recommends two discriminators, shape **and**
11-
colour — but only because those marks must survive favicon sizes. Our project marks are
12-
large-format only; the org mark remains every repo's favicon.
13-
14-
Rendered side by side, the per-family accent made each mark a **three-colour** object (green frame +
15-
gold frame + accent inner), which read as busy and diluted the org identity. Since favicon-size
16-
legibility is explicitly a non-goal, the second discriminator buys little. A single gold inner keeps
17-
every mark unmistakably part of one family, matches the brand palette exactly, and means a new repo
18-
needs only a new *shape*, not a new colour to keep harmonious. Templates get no symbol at all — they
19-
reuse the org chevron.
20-
21-
**Revisit trigger:** the org needs these marks at favicon scale, so shape alone no longer
22-
disambiguates; or a family grows large enough that a colour band materially helps wayfinding on the
23-
org site.
1+
# Project marks are two-colour, differentiated by symbol, not colour
2+
3+
Every project mark is the constant snake frame plus a single gold inner symbol, so repos are told
4+
apart by the shape of that symbol and never by a hue of their own. Per-family accent palettes were
5+
drawn and rejected: research on comparable systems recommends two discriminators, shape and colour,
6+
but only because those marks must survive favicon sizes, and ours are large-format only since the
7+
org mark stays every repo's favicon. Side by side the accent made each mark a three-colour object
8+
that read as busy and diluted the org identity, while one gold inner keeps the family coherent and
9+
means a new repo needs only a new shape. The two templates get no symbol at all and reuse the org
10+
chevron. `ALLOWED_COLORS` in `projects.py` holds the line; the pytest bars' four-step gold ramp is
11+
its one sanctioned exception.
Lines changed: 10 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,12 @@
11
# GitHub Discussions is the org's only owned channel
22

3-
**Decision:** Discussions is the org's sole owned support and feedback surface — org-level at
4-
`/orgs/modern-python/discussions` (backed by this repo, and where `SUPPORT.md` routes every
5-
project's users), plus per-repo tabs on the handful of repos with traffic to fill them. No Discord
6-
server, no Telegram group, and no per-repo tab enabled org-wide. When an *answerable* question
7-
arrives by any other route, it gets pushed to Discussions — "ask there so the next person finds it".
8-
9-
Chat rooms were the obvious alternative and are the one most often asked for. The durable-record
10-
argument is the load-bearing reason against opening them now: a chat answer is ephemeral, while a
11-
Discussions answer is searchable and Google-indexed, so it compounds — it also serves everyone who
12-
later hits the same error. Async also suits a solo maintainer in one timezone.
13-
14-
The stronger reason is the empty-room threshold. A young project's scarcest resource is the
15-
attention needed to seed a room, and an empty room is worse than no room: a visitor who lands on
16-
"3 members, last message 2 weeks ago" gets a worse signal than from a clean Discussions tab. The same
17-
arithmetic rejects enabling Discussions per-repo across all 28 repos — 20-odd empty tabs read as a
18-
dead org. The standing principle is to **borrow audiences before building our own**: participate
19-
where Python users already are rather than standing up rooms we cannot fill.
20-
21-
If rooms ever open, the scope is one org-wide room per platform, never per-repo. The whole stack
22-
shares one community, and the only rationale that keeps two rooms coherent rather than fragmenting a
23-
small one is a language/geo split (Russian-speaking Telegram, English/global Discord).
24-
25-
**Borrowing in practice:** a link back to our own pages is conditional, not standing. Link only
26-
where the linked page actually answers the question at hand (a docs page, or an existing Discussion),
27-
and never as a bare repo drop. The rejected alternative was a mandatory backlink on every reply: that
28-
turns participation into the drive-by self-promotion HN, Lobsters and r/Python each punish, and costs
29-
more standing than the referrals are worth. The obligation that *is* standing runs the other way,
30-
when a question answered in someone else's venue exposes a gap in our docs, that gap becomes an issue
31-
here.
32-
33-
**Revisit trigger:** launch week (the work is tracked in modern-python/.github#58). Rooms open *during* it, not before — launch traffic is what seeds
34-
them past the empty-room threshold. If a room is still inactive 30 days post-launch, fold it back
35-
into Discussions rather than keeping a dead room linked.
3+
GitHub Discussions, org-level at `/orgs/modern-python/discussions` and backed by this repo, is the
4+
only community surface the org runs; `SUPPORT.md` routes every project's users there, and per-repo
5+
tabs stay off except where a repo has traffic to fill one. A Discord server or Telegram group is the
6+
alternative asked for most often, rejected on the empty-room threshold rather than on the durability
7+
of a searchable answer: the scarcest resource is the attention needed to seed a room, and "3
8+
members, last message 2 weeks ago" is a worse signal than a clean Discussions tab. The same
9+
arithmetic rejects enabling Discussions across all 28 repos. The standing principle is to borrow
10+
audiences before building our own, linking back only where the linked page answers the question at
11+
hand, never as a bare repo drop. If rooms ever open they open during launch week, one org-wide room
12+
per platform, never per-repo.
Lines changed: 9 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,11 @@
11
# The `modern-di-flask` horn is drawn from Flask's own logo path
22

3-
**Decision:** Two project marks are built from a partner's literal logo path, recoloured into our
4-
palette: `modern-di-faststream` (FastStream's) and `modern-di-flask` (Flask's horn). Every other
5-
integration cue is a redrawn evocation or, where there was nothing to redraw from, an invention.
6-
7-
Flask is the one that needs a record. The permission we rely on is the **Flask Artwork License**,
8-
which explicitly allowed the logo "or a modified version" to be used to refer to the project. That
9-
license was dropped from the Pallets repo after Flask 1.0 and nothing replaced it, so today's Flask
10-
assets ship with no stated terms at all. The grant is historical, but it was explicit at the time we
11-
took it, and it is why the horn is a recolour rather than an evocation like its siblings.
12-
13-
**Revisit trigger:** Pallets publishes restrictive artwork terms, or asks. The horn is one function
14-
in `symbols.py` to redraw.
3+
Two project marks are a partner's literal logo path recoloured into our palette, FastStream's mark
4+
and Flask's drinking horn; every other integration cue is a redrawn evocation or, where there was
5+
nothing to redraw from, an invention. Flask is the one that needs a record. The permission relied on
6+
is the Flask Artwork License, which explicitly allowed the logo "or a modified version" to be used
7+
to refer to the project. Pallets dropped that license from its repo after Flask 1.0 and replaced it
8+
with nothing, so today's Flask assets ship with no stated terms at all. The grant is historical, but
9+
it was explicit when the path was taken, and it is why this mark is a recolour rather than an
10+
evocation like its siblings. If Pallets publishes restrictive terms or asks, `flask_horn` in
11+
`symbols.py` is one function to redraw.

0 commit comments

Comments
 (0)