Compare commits
2
Commits
v0.1.1
..
95dbd7d4dc
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
95dbd7d4dc | ||
|
|
65908ac97c |
@@ -1,110 +0,0 @@
|
||||
# 0046: Ekklesia's branding is never forced on an installation
|
||||
|
||||
- Status: Proposed
|
||||
- Date: 2026-10-03
|
||||
- Related: [ADR 0021](0021-modules-as-hostable-products.md),
|
||||
[ADR 0034](0034-host-owned-browser-authentication.md),
|
||||
[ADR 0037](0037-host-provided-outbound-email.md),
|
||||
[ADR 0038](0038-email-verification-and-password-recovery.md),
|
||||
[ADR 0039](0039-shared-design-tokens-and-elements.md),
|
||||
[ADR 0043](0043-display-offline-code-fallback.md),
|
||||
[ADR 0045](0045-split-dashboard-and-api-origins.md)
|
||||
|
||||
## Context
|
||||
|
||||
Ekklesia is software a church runs for its own people. The people who use an installation (members,
|
||||
visitors, volunteers running a screen) know the church, not the software behind it, and the church
|
||||
decides how it presents itself to them. Today the platform names itself in places those people see:
|
||||
the sign-in screen asks them to "Sign in to Ekklesia", the Dashboard's heading and page title read
|
||||
"Ekklesia", emails ask them to verify "your Ekklesia email address", and an offline screen in the
|
||||
sanctuary says it is "waiting for Ekklesia".
|
||||
|
||||
None of those were decided; they accumulated. This records the rule they should have followed, so
|
||||
every later screen, message, and module is held to it.
|
||||
|
||||
## Decision
|
||||
|
||||
### The principle
|
||||
|
||||
**Ekklesia's branding is never forced on an installation.** Anything a member, visitor, or volunteer
|
||||
can see is configurable by the installation and removable entirely. That includes, and is not
|
||||
limited to:
|
||||
|
||||
- page titles, headings, and the name of the application in a browser tab, an installed web app, or
|
||||
a bookmark;
|
||||
- sign-in, verification, recovery, and every other authentication screen;
|
||||
- emails: the sender's display name, the subject, and the body;
|
||||
- display screens, pairing screens, and offline and failure screens on a display;
|
||||
- error pages and error messages a person reads;
|
||||
- application names and icons, and any "powered by" or attribution text.
|
||||
|
||||
"Removable entirely" means an installation can show its own name, or no product name at all, and in
|
||||
either case no screen or message a person sees names Ekklesia.
|
||||
|
||||
### What is exempt
|
||||
|
||||
Internal identifiers are not branding and stay as they are: package names, module ids, URL paths
|
||||
(`/api/v1/…`, `/assets/ekklesia-dashboard/…`), HTTP header names, environment variable names, cookie
|
||||
names, CSS custom property names, element ids and `data-` attributes, storage, cache, and database
|
||||
names, and log field names. A person can find them only by opening developer tools or reading
|
||||
configuration, and renaming them would break installations for no one's benefit.
|
||||
|
||||
Tooling an operator runs to administer the installation (the command-line tools, Doctor, server logs,
|
||||
and startup messages) names the software being operated, as a package name does, and is exempt too.
|
||||
So are messages written only for developers: thrown errors that reach a console and never a page, and
|
||||
build-time diagnostics for module authors.
|
||||
|
||||
### How installations configure it
|
||||
|
||||
The platform takes the installation's name from configuration, once, and uses it everywhere a
|
||||
person-facing string would otherwise have said "Ekklesia". When no name is configured, the wording is
|
||||
neutral ("Sign in", "Verify your email address", "Waiting for the server") rather than falling back to
|
||||
"Ekklesia". The default installation therefore names nothing, which is what makes the principle
|
||||
checkable: a test can render every person-facing screen and message with no name configured and fail
|
||||
on any occurrence of "Ekklesia".
|
||||
|
||||
Browser pages receive the name the way they receive the API origin (ADR 0045): the API renders it
|
||||
into the page it serves at startup, so the image stays generic and nothing is decided at build time.
|
||||
An email's sender display name is the existing `EKKLESIA_SMTP_FROM_NAME` (ADR 0037); its subject and
|
||||
body use the same installation name.
|
||||
|
||||
Visual identity follows the same rule. The platform ships no logo, favicon, or icon today; any it
|
||||
ships later must be replaceable by the installation and removable entirely, and must not appear by
|
||||
default. Colours and type are the installation's theme (ADR 0039), not a mark.
|
||||
|
||||
### It applies to modules
|
||||
|
||||
A module's user-visible text follows the same principle. A module that names its host ("Open the
|
||||
Ekklesia Dashboard") also ties itself to one host, which ADR 0021 already asks modules not to do.
|
||||
Modules refer to the host generically ("the Dashboard") or not at all.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Every person-facing string that names the platform today becomes either the configured name or
|
||||
neutral wording. An implementation slice makes that change and adds the test that keeps it true.
|
||||
- New screens, emails, and modules are reviewed against this rule; "Ekklesia" in a person-facing
|
||||
string is a defect.
|
||||
- Internal identifiers, operator tooling, and developer diagnostics keep the name, so nothing
|
||||
operational is renamed.
|
||||
- An installation that wants to credit Ekklesia can do so in its own words; the platform never
|
||||
inserts that credit.
|
||||
|
||||
## Alternatives
|
||||
|
||||
- **Keep "Ekklesia" as the default and let installations override it.** Rejected: an installation
|
||||
that never thought to configure it would show the software's name to its people, which is forcing
|
||||
it by default, and "no occurrence of Ekklesia" could not be tested in the default state.
|
||||
- **Rename internal identifiers too.** Rejected: invisible to the people this protects, and costly
|
||||
to every installation and module.
|
||||
- **A configurable "powered by" line, on by default.** Rejected for the same reason as the first
|
||||
alternative.
|
||||
- **Per-string customization of every message.** Not needed for this principle: one installation
|
||||
name and neutral wording remove the product's name everywhere. Richer copy customization, if
|
||||
wanted, is separate work.
|
||||
|
||||
## Deferred
|
||||
|
||||
- The implementation: the setting, its delivery to pages and emails, the rewording, and the
|
||||
regression test.
|
||||
- Installation-supplied logos, icons, and favicons, and a web app manifest.
|
||||
- Translation and per-string copy customization.
|
||||
@@ -54,4 +54,3 @@ ADRs capture durable choices that affect more than one package or phase.
|
||||
- [0043: The display caches its shell and declared code, and nothing else](0043-display-offline-code-fallback.md) — Accepted
|
||||
- [0044: Ekklesia ships one self-hosted reference deployment, composed from pinned sources](0044-self-hosted-reference-deployment.md) — Accepted
|
||||
- [0045: The Dashboard and the API may live on separate origins](0045-split-dashboard-and-api-origins.md) — Accepted
|
||||
- [0046: Ekklesia's branding is never forced on an installation](0046-installation-owned-branding.md) — Proposed
|
||||
|
||||
Reference in New Issue
Block a user