-- Migration 020: Die Begruendung zieht in die Datenbank
--
-- Additive Migration. Der Migrator toleriert 1050/1060/1061/1062/1091 ("existiert bereits").

-- ---------------------------------------------------------------------------
-- Warum ueberhaupt
-- ---------------------------------------------------------------------------
-- Bisher galt eine Zweiteilung: Der Zustand eines Vorhabens stand hier, die
-- Begruendung in einer Markdown-Datei im Repository des Projekts, und
-- doc_anchor verwies darauf. Die Beschreibung der uebernommenen Eintraege
-- sagt es woertlich: "Die Begruendung steht weiterhin in der Datei - hier
-- steht nur der Zustand."
--
-- Das hatte zwei Folgen, die erst im Betrieb sichtbar wurden:
--
--   1. Die Roadmap-Tafel kann die Begruendung nicht zeigen. Sie sieht nur
--      die Datenbank; die Datei liegt auf einem Entwicklungsrechner.
--
--   2. Schwerer wiegt: Die Beschreibung des Werkzeugs dc_roadmap weist
--      Agenten an, vor dem erneuten Vorschlagen eines zurueckgestellten
--      Vorhabens "diesen Absatz" zu lesen. Ein Agent im Projekt polytrader
--      kann den Absatz nicht lesen - er liegt in einem fremden Repository.
--      Die Anweisung war nicht befolgbar.
--
-- Ab hier fuehrt das Deploymentcenter die Begruendung, und die Datei wird
-- daraus erzeugt (zweites Markerpaar dc:rationale). Damit gibt es einen Ort
-- statt zweier, und der Ort ist der, den alle erreichen.

-- ---------------------------------------------------------------------------
-- Ein eigenes Feld, nicht description
-- ---------------------------------------------------------------------------
-- description und rationale sind nicht dasselbe:
--   description  Was gemeldet wurde. Kommt vom Melder, oft von einer fremden
--                Maschine, und wird nicht umgeschrieben.
--   rationale    Warum wir uns so entschieden haben. Kommt von uns.
--
-- Zusammengelegt haette jede redaktionelle Ueberarbeitung der Begruendung
-- den urspruenglichen Wortlaut der Meldung ueberschrieben - und damit die
-- Grundlage, auf der entschieden wurde.
--
-- MEDIUMTEXT und nicht TEXT: Die laengsten vorhandenen Abschnitte liegen bei
-- rund 2 KB, aber eine Begruendung darf wachsen, und die 64-KB-Grenze von
-- TEXT ist keine, die man beim Schreiben im Kopf haben moechte.
ALTER TABLE bugtracker_items
  ADD COLUMN rationale MEDIUMTEXT NULL AFTER doc_anchor;

-- Wann die Begruendung zuletzt angefasst wurde. Getrennt von updated_at,
-- weil dieses bei jeder Statusaenderung hochgeht und dann nicht mehr
-- beantwortet, ob die Begruendung noch dem entspricht, was heute gilt.
ALTER TABLE bugtracker_items
  ADD COLUMN rationale_updated_at DATETIME NULL AFTER rationale;

-- ---------------------------------------------------------------------------
-- Auch Bereiche haben eine Begruendung
-- ---------------------------------------------------------------------------
-- Beim Einlesen der vorhandenen Datei stellte sich heraus, dass ein guter
-- Teil der Prosa gar nicht an einem Vorhaben haengt, sondern am Bereich:
-- neun Abschnitte der Form "## A - Supervisor und Befunde" mit mehreren
-- Absaetzen, in denen die Grundentscheidung des jeweiligen Bereichs steht.
--
-- roadmap_epics.summary gibt es bereits, aber das ist eine Zeile fuer die
-- Uebersichtstabelle. Diese Abschnitte sind bis zu dreissig Zeilen lang.
-- Ohne ein eigenes Feld haette der erzeugte Block sie beim ersten Lauf
-- ueberschrieben - also genau den Text, der am schwersten wieder zu
-- beschaffen waere.
ALTER TABLE roadmap_epics
  ADD COLUMN rationale MEDIUMTEXT NULL AFTER summary;

ALTER TABLE roadmap_epics
  ADD COLUMN rationale_updated_at DATETIME NULL AFTER rationale;