STXT
ESEN .stxt

RFCs and technical proposals

A technical proposal (an internal RFC, an architecture decision record, a design document) is drafted, discussed and accepted or rejected. In STXT it is still a text document, but its status, its authors and its relations with other proposals are data.

A proposal

RFC (com.acme.rfc):
	Id: RFC-013
	Title: Unification of the configuration system
	Status: Review
	Authors:
		Author: Platform Team
	Created: 2026-01-05
	Updated: 2026-01-10

	Context >>
		Several configuration formats coexist today in the internal services,
		each with its own validation rules and its own tooling. Every new team
		picks one, and support has to know them all.

	Proposal >>
		Adopt a single configuration format for internal services, with one
		template per service type maintained by Platform.

	Alternatives:
		Alternative: Keep the current formats
			Pros >>
				No initial cost.
			Cons >>
				Fragmentation grows with every new service.
		Alternative: Standardize on the most widespread format today
			Pros >>
				Tooling and knowledge already present in the teams.
			Cons >>
				Its validation is external.

In this example we have:

  • Header: Id, Title, Status, Authors and the dates. They are data.
  • Body: Context and Proposal. They are block nodes, with the names the organization already uses in its proposals.
  • Alternatives: each one is a node with its title, and its pros and cons are text.

The template

Template (@stxt.template): com.acme.rfc
	Structure >>
		RFC:
			Id: (1)
			Title: (1)
			Status: (1) ENUM [Draft, Review, Accepted, Rejected, Deprecated]
			Authors: (1)
				Author: (+)
			Created: (?) DATE
			Updated: (?) DATE
			Accepted date: (?) DATE
			Related: (?)
				Reference: (+)
			Context: (1) TEXT
			Proposal: (1) TEXT
			Alternatives: (?)
				Alternative: (*)
					Pros: (?) TEXT
					Cons: (?) TEXT
			Decision: (?) TEXT
			Consequences: (?) TEXT
			Comments: (?)
				Comment: (*)
					Author: (1) @Author
					Date: (1) DATE
					Text: (1) TEXT

The template requires the minimum of every proposal: identifier, title, status, an author, context and proposal. The rest is optional, because a draft has no decision or consequences yet. The text is not restricted: a TEXT accepts any content.

The ENUM of Status is the life cycle. A proposal is in one of five statuses.

A proposal that does not validate

# ERROR: this document does not validate
RFC (com.acme.rfc):
	Id: RFC-014
	Title: Migration of the billing services
	# `Pending` is not a status of the list
	Status: Pending
	# `Authors` is missing
	# `Context` is missing
	Proposal >>
		Migrate the billing services to the single format.

The life cycle

Weeks later, the proposal is accepted. This is the diff between the two versions:

 	Title: Unification of the configuration system
-	Status: Review
+	Status: Accepted
 	Authors:
 		Author: Platform Team
 	Created: 2026-01-05
-	Updated: 2026-01-10
+	Updated: 2026-01-18
+	Accepted date: 2026-01-18

...

+	Decision >>
+		Gradual adoption is approved. Platform publishes the templates before the
+		end of the quarter.
+
+	Consequences >>
+		New services use the single format from their creation. Existing ones
+		migrate in their next major version, with no deadline.
+
+	Comments:
+		Comment:
+			Author: Mery Adams
+			Date: 2026-01-12
+			Text >>
+				I propose that the migration of existing services has no
+				deadline.

Changing status is changing one line. The review comments are kept in the document itself, with author and date, next to the decision.

Relations between proposals

RFC (com.acme.rfc):
	Id: RFC-020
	Title: Retirement of the previous configuration system
	Status: Draft
	Authors:
		Author: Joan Costa
	Related:
		Reference: RFC-013
		Reference: RFC-007

	Context >>
		With the adoption of the single format (RFC-013), the previous system has
		no new services and a growing maintenance cost.

	Proposal >>
		Retire the previous system once the services still using it have migrated.

RFC-013 appears twice: in Related, as data, and in Context, as text. With the data, a program walking the proposals directory can answer what depends on what, or which drafts cite a rejected proposal.

How it is used

  • The proposals live in a directory of the repository, one per file, with the template in .stxt/.
  • stxt validate --recursive rfcs/ (The command line) runs on every change.
  • A program generates the index of proposals by status, or warns about those that have been in Review for more than a month.

Limits

Validation does not check relations between documents (that RFC-007 exists, or that an accepted proposal does not cite a rejected one). That is done by the program that walks the directory.

STXT does not replace the review tool either: the comments in the example are a record of the discussion, without threads or notifications.