Change proposals, decision records, and lifecycle tracking for the ARCORIS ecosystem.
Core Platform · Docs · Handbook · Community · Examples
Proposals · Decisions · Lifecycle · Review · Graduation · Supersession · Archive
Overview: Purpose · Start here · Intended audiences
Scope: What belongs here · What does not belong here · Source of truth
Structure: Repository map · Change map · Enhancement principles
Repository: Contributing · Repository status
This repository is the change-management and decision-tracking repository for ARCORIS.
It exists to capture major proposals, record accepted decisions, track change lifecycle state, and preserve historical outcomes such as superseded, rejected, or withdrawn work.
This repository is not the canonical home of the stable public system description. It is the canonical home for change records, decision records, lifecycle rules, and archive history.
Use the Enhancements Index as the primary entry point for enhancement navigation, reading order, and topic-based access paths.
The index should direct readers to overview material, process rules, decision catalogs, archive navigation, and the active proposal space.
Use this repository for material that defines, evaluates, records, tracks, or archives major changes to ARCORIS.
Typical content includes:
- major change proposals before they become stable platform reality;
- decision records for accepted architecture, compatibility, platform, security, and deprecation outcomes;
- lifecycle rules for review, approval, graduation, supersession, withdrawal, and archival;
- implementation tracking for accepted work that still needs coordinated follow-through;
- catalog pages that map active, accepted, and historical change records;
- archive structures for rejected, withdrawn, and superseded proposals and decisions.
This repository should answer questions such as:
- what requires an enhancement;
- what is currently proposed;
- what has already been decided;
- what was accepted, rejected, withdrawn, or superseded;
- what still requires cross-repository updates before a change is considered complete.
This repository must not absorb responsibilities that belong elsewhere.
The following should live outside this repository:
- canonical public system explanation, stable architecture narratives, and user-facing platform guidance;
- engineering and documentation operating rules, templates, and review discipline not specific to enhancement lifecycle;
- governance, roles, ownership, meetings, and community coordination;
- runnable examples, environment baselines, demos, and scenario material;
- implementation-near technical documentation that belongs next to source code.
If a proposal becomes accepted and stable, its canonical public explanation should be promoted to Docs, while its change history remains here.
ARCORIS uses multiple repositories with different responsibilities. This repository is only one layer of that system.
| Repository | Role |
|---|---|
| Core Platform | Main code repository for the platform |
| Repository | Role |
|---|---|
| Docs | Public documentation and canonical system explanation |
| Handbook | Engineering and documentation operating rules |
| Community | Governance, roles, coordination, and contributor growth |
| Enhancements (this repository) | Major proposals, decisions, lifecycle tracking, and archive history |
| Examples | Runnable examples, baselines, demos, and scenario material |
This repository should track change lifecycle and decision history without taking over the stable responsibilities of the repositories those changes eventually affect.
The repository is organized around a small set of durable reader-facing entry points and record spaces.
| Section | Role |
|---|---|
| Overview | Mission, scope, change boundaries, change types, repository mapping, and status model |
| Process | Review, approval, lifecycle, graduation, implementation tracking, and cross-repository update rules |
| Catalog | Navigation across active proposals, decisions, archive state, and release mapping |
| Enhancements Index | Primary entry point into the full enhancements documentation set |
| Area | Role |
|---|---|
proposals/ |
Active proposal space organized by domain |
decisions/ |
Accepted decision records organized by topic |
archive/proposals/ |
Rejected, withdrawn, and superseded proposal history |
archive/decisions/ |
Superseded decision history |
Detailed navigation and reading order should be defined in the Enhancements Index and in the section index pages themselves, not in this root README.
This repository serves several audiences:
- proposal authors who need to understand whether a change belongs here and how to structure it;
- reviewers and maintainers who need a consistent lifecycle for evaluating, accepting, tracking, and closing major changes;
- engineers and architects who need a durable record of why major system decisions were made;
- contributors who need to know whether work is still proposed, already accepted, or no longer active;
- future readers who need traceable history instead of rediscovering earlier design work.
Because these audiences differ, the repository should optimize for traceability, lifecycle clarity, and repository-boundary discipline.
This repository should hold the canonical explanation of the change lifecycle and decision history for ARCORIS.
That means:
- active major proposals should be tracked here;
- accepted major decisions should be recorded here;
- rejected, withdrawn, and superseded records should remain discoverable here;
- lifecycle rules for enhancement review, graduation, and archival should be documented here.
If a topic exists in multiple forms, the boundary is simple:
- major proposal, accepted decision, lifecycle state, or archive record -> Enhancements
- stable public system explanation -> Docs
- operating rules, writing policy, and review discipline -> Handbook
- governance and coordination -> Community
- runnable and demonstrative material -> Examples
- implementation-near technical detail -> Core Platform
A change may begin here, but it must not remain documented only here once its stable public behavior or architecture needs canonical explanation elsewhere.
Material in this repository should follow a small set of strict principles:
- Only substantial change belongs here. Minor fixes, routine maintenance, and local implementation detail should not be escalated into enhancements.
- Status must be explicit. Readers should be able to tell whether work is proposed, accepted, rejected, withdrawn, superseded, or archived.
- Decision history must remain discoverable. Old work should not disappear when it stops being current.
- Promotion of accepted knowledge matters. Once a change becomes stable platform reality, its canonical public explanation must move to the appropriate repository.
- Traceability over narrative sprawl. Proposal, decision, implementation tracking, and archive relationships should remain easy to follow.
- Repository boundaries must hold. Enhancements should not become a substitute for Docs, Handbook, Community, Examples, or code-near documentation.
- Docs-as-code rigor. Change records should be reviewable, versioned, and maintainable like source code.
A good change in this repository usually does one or more of the following:
- introduces a substantial new proposal with clear scope and motivation;
- records an accepted decision in a durable and searchable form;
- clarifies lifecycle rules for review, graduation, supersession, withdrawal, or archival;
- improves catalog navigation across active and historical records;
- strengthens traceability between proposals, decisions, implementation follow-through, and eventual documentation updates;
- removes ambiguity about where a change belongs and how it should progress.
Changes should not move stable public documentation, operating rules, governance material, runnable examples, or implementation-near technical documentation into this repository.
This repository already reflects the core domains of enhancement responsibility: active proposals, accepted decisions, archive state, and reader-facing process documentation.
The current structure also supports a strong split between user-facing guidance under docs/ and record storage under proposals/, decisions/, and archive/.
As the repository evolves, section index pages, catalog pages, and lifecycle rules should continue to reinforce this repository’s role as the canonical home for major change records and decision history.