STXT
ESEN .stxt

RFCs y propuestas técnicas

Una propuesta técnica (un RFC interno, un registro de decisión de arquitectura, un documento de diseño) se redacta, se discute y se acepta o se rechaza. En STXT sigue siendo un documento de texto, pero su estado, sus autores y sus relaciones con otras propuestas son datos.

Una propuesta

RFC (com.acme.rfc):
	Id: RFC-013
	Title: Unificación del sistema de configuración
	Status: Review
	Authors:
		Author: Platform Team
	Created: 2026-01-05
	Updated: 2026-01-10

	Context >>
		Hoy conviven varios formatos de configuración en los servicios internos,
		cada uno con sus propias reglas de validación y sus propias herramientas.
		Cada equipo nuevo elige uno, y el soporte tiene que conocerlos todos.

	Proposal >>
		Adoptar un único formato de configuración para los servicios internos, con
		una plantilla por tipo de servicio mantenida por Plataforma.

	Alternatives:
		Alternative: Mantener los formatos actuales
			Pros >>
				Sin coste inicial.
			Cons >>
				La fragmentación crece con cada servicio nuevo.
		Alternative: Estandarizar en el formato más extendido hoy
			Pros >>
				Herramientas y conocimiento ya existentes en los equipos.
			Cons >>
				Su validación es externa.

En este ejemplo tenemos:

  • Cabecera: Id, Title, Status, Authors y las fechas. Son datos.
  • Cuerpo: Context y Proposal. Son nodos block, con los nombres que la organización ya usa en sus propuestas.
  • Alternativas: cada una es un nodo con su título, y sus pros y contras son texto.

La plantilla

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

La plantilla exige lo mínimo de toda propuesta: identificador, título, estado, un autor, contexto y propuesta. El resto es opcional, porque un borrador todavía no tiene decisión ni consecuencias. El texto no se restringe: un TEXT admite cualquier contenido.

El ENUM de Status es el ciclo de vida. Una propuesta está en uno de cinco estados.

Una propuesta que no valida

# ERROR: este documento no valida
RFC (com.acme.rfc):
	Id: RFC-014
	Title: Migración de los servicios de facturación
	# `Pendiente` no es un estado de la lista
	Status: Pendiente
	# Falta `Authors`
	# Falta `Context`
	Proposal >>
		Migrar los servicios de facturación al formato único.

El ciclo de vida

Semanas después, la propuesta se acepta. Este es el diff entre las dos versiones:

 	Title: Unificación del sistema de configuración
-	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 >>
+		Se aprueba la adopción progresiva. Plataforma publica las plantillas antes
+		del fin del trimestre.
+
+	Consequences >>
+		Los servicios nuevos usan el formato único desde su creación. Los existentes
+		migran en su siguiente versión mayor, sin fecha límite.
+
+	Comments:
+		Comment:
+			Author: Mery Adams
+			Date: 2026-01-12
+			Text >>
+				Propongo que la migración de los servicios existentes no tenga
+				fecha límite.

Cambiar de estado es cambiar una línea. Los comentarios de la revisión se guardan en el propio documento, con autor y fecha, junto a la decisión.

Relaciones entre propuestas

RFC (com.acme.rfc):
	Id: RFC-020
	Title: Retirada del sistema de configuración anterior
	Status: Draft
	Authors:
		Author: Joan Costa
	Related:
		Reference: RFC-013
		Reference: RFC-007

	Context >>
		Con la adopción del formato único (RFC-013), el sistema anterior queda
		sin servicios nuevos y con coste de mantenimiento creciente.

	Proposal >>
		Retirar el sistema anterior una vez migrados los servicios que aún lo usan.

RFC-013 aparece dos veces: en Related, como dato, y en Context, como texto. Con el dato, un programa que recorra el directorio de propuestas puede responder qué depende de qué, o qué borradores citan una propuesta rechazada.

Cómo se trabaja

  • Las propuestas viven en un directorio del repositorio, una por fichero, con la plantilla en .stxt/.
  • stxt validate --recursive rfcs/ (La línea de comandos) se ejecuta en cada cambio.
  • Un programa genera el índice de propuestas por estado, o avisa de las que llevan más de un mes en Review.

Límites

La validación no comprueba relaciones entre documentos (que RFC-007 exista, o que una propuesta aceptada no cite una rechazada). Eso lo hace el programa que recorre el directorio.

STXT tampoco sustituye a la herramienta de revisión: los comentarios del ejemplo son un registro de la discusión, sin hilos ni notificaciones.