Decision Making

Ideal is developed in the open, and its decisions are made in the open too. Anyone can participate in any discussion, and all significant decisions are documented as versioned files in the repository.

Everyday Decisions

Most changes — bug fixes, documentation improvements, small enhancements — are handled through the regular patch review process. A maintainer reviews the patch, provides feedback if needed, and merges it when ready.

For these changes, the project uses lazy consensus: if no maintainer raises an objection within a reasonable time, the change is considered accepted. Silence is assent.

Architecture Decision Records

Significant decisions that affect the project as a whole — its direction, architecture, or community policies — are documented as Architecture Decision Records (ADRs). An ADR is a short Markdown file that captures what was decided and why. Project ADRs live in the ideal-docs repository, submitted and reviewed as patches through ideal-devel like any other contribution.

What Requires a Project ADR

A project ADR is needed for decisions that cross component boundaries or affect the project as a whole:

• Cross-cutting architectural choices (IPC protocols, plugin interfaces, shared data formats).
• Decisions that affect multiple components or the project's overall direction.
• Changes to project policies (governance, contribution process, licensing).
• Standards that all components must follow.

If you're unsure, ask on ideal-devel. When in doubt, write the ADR — a short one is better than none.

Creating an ADR

ADRs live in community/decisions/ and are named NNNN-short-title.md, where NNNN is the next available four-digit number. Use this template:

---
adr: NNNN
date: YYYY-MM-DD
status: proposed
---

# Short descriptive title

## Context

Describe the situation that calls for a decision. What problem exists? What forces are at play?
This section states facts, not arguments.

## Decision

What was decided, and why? Write in active voice: "We will..."

## Alternatives Considered

What other options were evaluated? Why were they not chosen?

## Consequences

What are the effects of this decision — positive, negative, and neutral?
What becomes easier? What becomes harder? What follow-up work does this create?

The adr field is the ADR number as a plain integer. The ADR-NNNN: prefix and the status badge are added automatically when the document is rendered — the title in the file is just the description.

Submitting for Review

Submit the ADR as a patch to the ideal-devel mailing list, following the standard patch submission process. Use a subject line that makes the intent clear:

[PATCH ideal-docs] Add ADR-0042: switch to Wayland

Anyone can review and reply to the patch thread with questions, concerns, or support.

Discussion

The patch thread on ideal-devel is the discussion. Contributors are encouraged to:

• Ask clarifying questions.
• Raise technical or practical concerns.
• Suggest modifications to the proposed decision or the alternatives analysis.
• Express support and explain why.

The author may revise the ADR in response to feedback by sending a new version of the patch (-v2, -v3, ...). Significant decisions should allow at least a week for the community to engage before being merged.

Reaching a Decision

The project lead decides when consensus has been reached and acts accordingly:

Action	Meaning
Merge with status: accepted	The decision is adopted.
Merge with status: rejected	The proposal was considered and declined.
Merge with status: deferred	The proposal has merit but the timing is not right.
Request revision	The proposal needs more work before a decision can be made.

Both accepted and rejected ADRs are merged into the repository. A rejected ADR is still a record — it explains what was considered and why it was not adopted, which avoids covering the same ground again in the future.

The project lead replies to the patch thread with the rationale before merging. A decision without explanation is not acceptable.

note

The project lead is not a dictator. The role is to recognize consensus, not to override it. The lead may break ties when genuine disagreement persists and all perspectives have been thoroughly discussed, but this should be rare. A pattern of decisions that ignore community input would undermine the project's legitimacy.

Superseding a Decision

If a previously accepted ADR is later reversed or significantly changed, a new ADR is created. The original is updated to status: superseded and superseded_by: N (the number of the new ADR). ADRs are never deleted.

Component Decision Records

Any significant decision with lasting consequences that does not meet the criteria for a project ADR is documented as a component decision record within that component's own repository.

Component decision records use the same template and the same review process as project ADRs, with the component maintainer or the project lead acting as the decision-maker. The differences are:

• They live in decisions/ within the component repository, not in ideal-docs.
• Each component maintains its own numbering sequence, independent of project ADRs.
• They are submitted as patches with the component's prefix.

Since all components share the same mailing list, reviewers may identify during discussion that a component ADR has broader implications. In that case, the author resubmits it as a new patch against ideal-docs with a project-level number. The original component ADR is merged as rejected, with its Decision section noting that the decision was escalated and referencing the project ADR that replaces it.

Roles

Project Lead

The project lead is responsible for the overall direction of Ideal. The lead:

• Facilitates discussions and helps proposals move forward.
• Recognizes consensus and merges or closes ADR patches.
• Breaks ties when consensus cannot be reached after thorough discussion.
• Has final say on matters that affect the project's long-term vision.

The current project lead is cpradog.

Maintainers

Maintainers have push access to one or more Ideal repositories. They:

• Review and merge patches.
• Triage issues.
• Participate in ADR discussions.
• Help contributors navigate the project.

Maintainers are added by the project lead based on sustained, quality contributions and demonstrated judgment.

Contributors

Anyone who has submitted a patch, filed an issue, or participated in a discussion is a contributor. Contributors can:

• Submit patches and ADRs.
• Participate in all discussions.

There is no formal membership requirement. Show up, participate constructively, and your input carries weight.

Transparency

All decisions that affect the project must be made on the public mailing lists. Private discussions between maintainers may happen for logistical coordination, but any decision that results from them must be summarized and ratified publicly on ideal-devel.

The Decision Records section is the project's authoritative decision log.