-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #7 from tollwerk/doc
Dokumentiere einen ersten Entwurf des Release-Konzepts
- Loading branch information
Showing
3 changed files
with
174 additions
and
56 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,174 @@ | ||
= BIK BITV-Test Release-Konzept | ||
:author: Joschi Kuphal | ||
:email: [email protected] | ||
:revdate: June 18th, 2022 | ||
:revnumber: 1.0.0 | ||
:lang: de | ||
:orgname: tollwerk GmbH | ||
:description: Automatisierte und manuelle Prozesse rund um die Veröffentlichung des BIK BITV-Test-Prüfverfahrens | ||
:keywords: BITV, WCAG, Accessibility, Test | ||
:toc: | ||
|
||
== Vorbemerkung | ||
|
||
Die Prüfschritte des https://github.com/BIK-BITV/BIK-Web-Test[BIK BITV-Test-Prüfverfahrens] stehen seit einiger Zeit öffentlich in einem Github-Repository zur Verfügung. | ||
Sie können dort von Interessierten eingesehen, kommentiert, diskutiert und kollaborativ weiterentwickelt werden. | ||
Die Weiterentwicklung der Prüfschritte ist bislang ein kontinuierlicher Vorgang, der keine Ausprägung von bestimmten Meilensteinen vorsieht. | ||
Die Einführung neuer Prüfschritte wurde zu bestimmten Zeitpunkten durchgeführt und in der Kommunikation wird dann auf den „Stand vor xx.xx.xxxx“ und den „Stand nach xx.xx.xxxx“ verwiesen. | ||
|
||
Die bislang fehlende Referenzierbarkeit eines bestimmten Standes eines Prüfschritts kann zu zeitabhängigen Ambiguitäten beim Nachvollziehen von Bewertungen führen. | ||
Um dem entgegenzuwirken, sollen künftig eindeutige Stände des Prüfverfahrens „eingefroren“ werden, so dass eine klare Bezugnahme möglich ist. | ||
|
||
Ein weiteres Problem für aktiv Prüfende ist, dass es derzeit nicht einfach möglich ist, Veränderungen der Prüfschritte zu erkennen und nachzuvollziehen, so dass sich die Prüfpraxis mit dem Verfahren weiterentwickeln kann. | ||
Zwar kommt die Speicherung der Prüfschritte auf Github grundsätzlich mit alle notwendigen Werkzeugen, alle Änderungen granular nachvollziehen zu können. | ||
Jedoch existiert keine anschauliche Zusammenstellung dieser Änderungen, so dass ein Gesamtbild nur mit sehr viel Mühe gewonnen werden kann. | ||
|
||
Das vorliegende Konzept beschäftigt sich mit den Fragen: | ||
|
||
- Wie kann ein koordiniertes Veröffentlichen von Meilensteinen des Prüfverfahrens aussehen? | ||
- Wie können die Änderungen am Prüfverfahren möglichst aufwandsfrei anschaulich dargestellt werden? | ||
- Welche Prozesse können und sollten an die Veröffentlichung eines Meilensteins anschließen? | ||
|
||
Im Git-Repository dieses Konzepts sowie in den Einstellungen zum Repository auf Github finden sich bereits einige prototypische Experimente, die z. T. unverändert oder mit Anpassungen in die Umsetzung des Konzepts übernommen werden können. | ||
Darüber hinaus enthält das Repository eine Kopie der Prüfschritte des BITV-Tests (Web), um realistisch damit experimentieren zu können. | ||
|
||
== Tools & Standards | ||
|
||
Die folgenden Abschnitte stellen verschiedenen https://github.com/[Github]-Konzepte und -Funktionalitäten sowie sinnvolle Standards vor, aus denen schließlich ein Vorgehensvorschlag modelliert wird. | ||
|
||
=== Releases & Tags | ||
|
||
Git als Versionierungssystem bietet die Möglichkeit, einen bestimmten Stand einer Codebasis bzw. des Inhalts eines Git-Repositories mit einer eindeutigen Bezeichnung, einem sog. *Tag* zu versehen. | ||
Der betreffende Repository-Stand ist dann anhand dieses Tags eindeutig referenzierbar (Hinweis: Auch ohne Tags ist es möglich, zu jedem beliebigen vergangenen Stand eines Repositories zu springen). | ||
Ein Tag ist im Grunde eine frei wählbare, innerhalb des Repositories eindeutige Zeichenkette. | ||
In der Praxis ist es üblich, *Versionsnummer* als Tags zu verwenden (statt freie Texte; <<semver,siehe unten>>). | ||
|
||
Github als Community-Plattform bietet zusätzlich die Möglichkeit, getaggte Stände eines Repositories als sog. *Releases* zu veröffentlichen. | ||
Releases verfügen — neben der eindeutigen Bezugnahme auf ein Tag — zusätzlich über: | ||
|
||
* eine *Release-Beschreibung*, die beliebige Informationen zum Release transportieren kann, | ||
* *Assets* zum Release; dabei handelt es sich um beliebige Dateianhänge, beispielsweise kompilierte Softwareversionen, Dokumentationen o. ä. Github fügt standardmäßig Archive des Repository-Inhaltes in mehreren Formaten als Assets an jedes Release. | ||
|
||
[[semver]] | ||
=== Semantische Versionierung | ||
|
||
https://semver.org/[Semantische Versionierung] („SemVer“) ist ein in der Open-Source-Softwareentwicklung verbreiteter und akzeptierter Standard zur Konstruktion und Vergabe von Versionsnummern. | ||
SemVer-Versionsnummern bestehen im Wesentlichen aus 3 aneinandergereihten und durch Punkte getrennte Zahlen (und möglicherweise einen Präfix sowie Suffix). | ||
|
||
[source] | ||
---- | ||
1.2.3 | ||
| | \_ PATCH-Version | ||
| \___ MINOR-Version | ||
\_____ MAJOR-Version | ||
---- | ||
|
||
Die einzelnen Stellen in der Versionsnummer haben jeweils bestimmte Bedeutungen: | ||
|
||
MAJOR:: wird erhöht, wenn API-inkompatible Änderungen veröffentlicht werden, | ||
MINOR:: wird erhöht, wenn neue Funktionalitäten, welche kompatibel zur bisherigen API sind, veröffentlicht werden, und | ||
PATCH:: wird erhöht, wenn die Änderungen ausschließlich API-kompatible Bugfixes umfassen. | ||
|
||
[[changelog]] | ||
=== Keep A Changelog | ||
|
||
Der https://keepachangelog.com[Keep a Changelog]-Standard setz sich für das konsequente und koordinierte Führen eines Änderungsprotokolls für jede Software ein. | ||
Er schlägt dazu bestimmte Konventionen vor: | ||
|
||
- Jedes Projekt sollte in seinem Wurzelverzeichnis eine Datei mit dem Namen `CHANGELOG.md` (oder nur `CHANGELOG`) im https://markdown.de/[Markdown]-Format haben. | ||
- In dieser Datei sollen — in strukturierter Form — alle nennenswerten Änderungen zu allen veröffentlichten Versionen des Projekts dokumentiert werden. | ||
Der Standard schlägt zur übersichtlichen Gliederung eine https://keepachangelog.com/de/1.0.0/#how[Reihe von Kategorien] vor, in welche die Änderungen gruppiert werden sollen. | ||
- Zusätzlich ist es möglich, noch unveröffentlichte Änderungen unter einer speziellen Überschrift („Unreleased“) darzustellen, sodass eine Vorschau entsteht, was in der nächsten Veröffentlichung enthalten sein wird. | ||
|
||
[[pullrequest]] | ||
=== Pull-Requests | ||
|
||
Ein _Pull Request_ (oder _Merge Request_) bezeichnet in der Versionsverwaltung einen Arbeitsablauf, Quellcode-Änderungen in Softwareprojekten vorzunehmen. | ||
Ziel eines _Pull Requests_ ist, Änderungen aus einem _Branch_ (also einer abgeleiteten Arbeitsversion) in die eigentliche Quellcode-Basis zu übernehmen. | ||
Wird ein _Pull Request_ akzeptiert, so spricht man von einem _Merge_, wird er geschlossen, so spricht man von einem _Close_. | ||
|
||
Beim BITV-Test-Prüfverfahren stellen _Pull Requests_ den Standard-Weg dar, auf dem Änderungen in die Prüfschritte eingehen (sollen). | ||
Community-Mitglieder (oder die Projekt-Verwaltenden selbst) entwerfen Änderungsvorschläge für die Prüfschrittbescheibungen und übertragen diese in individuellen _Branches_ ins Repository. | ||
Sie reichen die Änderungen als Anträge zur Übernahme in den Haupt-Branch ein. | ||
In diesem Zug müssen sie wenigstens einen *Titel* für ihren _Pull Request_ angeben und haben zusätzlich die Möglichkeit, eine ausführlichere Erläuterung als *Nachricht* beizufügen (was beim BITV-Test selten vorkommen dürfte, da der Titel in der Regel genug Aussage transportieren kann). | ||
|
||
Nicht selten sind _Pull Requests_ das Ergebnis einer Themendiskussion (_Issue_) oder gehen damit einher. | ||
Sowohl _Issues_, als auch _Pull Requests_ sind auf Github dauerhaft einsehbar — auch nachdem sie übernommen oder geschlossen wurden. | ||
|
||
[CAUTION] | ||
Neben der Möglichkeit, Änderungen per _Pull Request_ in die Quellcode-Basis einzubringen, können diese auch direkt in den Haupt-_Branch_ übertragen werden. | ||
Wird dies zugelassen, besteht die Gefahr, dass Änderungen Eingang finden, die nicht ausreichend geprüft wurden und (bei Softwareprojekten) zu ernsthaften Problemen führen können. | ||
Diese Möglichkeit sollte daher allenfalls Verwaltenden mit einer besonderen Vertrauensstellung und mit viel Erfahrung vorbehalten sein. | ||
Im Idealfall wird durch entsprechende Einstellungen dafür gesorgt, dass eine direkte Veränderung der Code-Basis generell nicht möglich ist. | ||
|
||
=== Labels | ||
|
||
Um die Bearbeitungsabläufe benutzerfreundlich zu gestalten, bietet Github an, _Issues_ und <<pullrequest,_Pull Requests_>> mit Etiketten, sog. _Labels_ zu versehen. | ||
Die Labels können mit einer Farbe assoziiert und frei angelegt werden (Github bringt eine Standard-Vorauswahl mit, die jedoch verworfen oder verändert werden kann). _Labels_ machen es einfach, Themen zu kategorisieren, priorisieren oder anderweitig zu organisieren. | ||
Sie dienen rein der Oberflächennutzung und haben keine funktionale Auswirkung auf die Quellcode-Basis. | ||
|
||
[[githubactions]] | ||
=== Github Actions | ||
|
||
https://de.github.com/features/actions[_Github Actions_] bringen die Möglichkeit, beim Eintreten bestimmter Ereignisse in einem Repository nahezu beliebige Prozesse anzustoßen und ablaufen zu lassen. | ||
Beispielsweise können beim Einreichen von neuem Code automatisierte Tests die Gültigkeit und Funktionstüchtigkeit der neuen Programmierung prüfen und Alarm schlagen, sollte ein Problem erkannt werden. | ||
Oder es können beim Veröffentlichen eines Releases Kompilierschritte vollzogen werden, die für die lauffähige Form der Software notwendig sind. | ||
|
||
_Github Actions_ führen dazu sog. _Workflows_ aus, die in https://yaml.org/[YAML]-Dateien artikuliert und direkt im Repository gespeichert werden. | ||
Die Funktionalität steht für öffentliche Repositories kostenfrei zur Verfügung. | ||
|
||
== Release-Konzept | ||
|
||
Aufbauend auf den oben dargestellten Tools und Standards wird folgender Vorgehensvorschlag unterbreitet. | ||
|
||
Prüfschritt-Änderungen nur über Pull Requests:: Es wird festgelegt, dass Änderungen an den Prüfschritten *ausschließlich über <<pullrequest,Pull Requests>>* erfolgen dürfen. Direktes Übertragen von Code-Änderungen in den Haupt-Branch ist allenfalls zur technischen Administration und zum Ändern der Programmierteile des Repositories (z. B. Github-Action-Workflows) gestattet. _Pull Requests_ sind generell *so granular wie möglich* zu halten. Zulässig sind nur *Änderungen an einem Prüfschritt je Pull Request*. | ||
[[prtitle]] | ||
Pull-Request-Titel:: Die Betitelung von Pull Requests unterliegt <<pullrequesttitel,besonderen Regeln>> und ist mit entsprechender Sorgfalt durchzuführen, da die Titel für die automatische Erzeugung von Release-Notizen sowie zur Aktualisierung des Änderungsprotokolls herangezogen werden. Da die Titel initial von den Antragstellenden verfasst werden, ist es Aufgabe der Verwaltenden, die Formulierung der Titel auf die Richtlinie hin zu prüfen und ggf. anzupassen, *bevor ein Pull Request akzeptiert wird*. | ||
[[prlabels]] | ||
Labels für Pull Requests:: Jedem _Pull Request_ sind zwei Label aus zwei vorgegebenen Taxonomien zu vergeben: | ||
+ | ||
-- | ||
. In Abhängigkeit davon, wie gravierend die Änderungen sind, die mit dem _Pull Request_ einhergehen, steuert ein *Versionierungs-Label* (`version:*`), ob sich daraus eine PATCH-, MINOR- oder MAJOR-Versionsänderung ergeben sollt. Wird kein Versionierungs-Label vergeben, so wird automatisch eine PATCH-Versionsänderung hervorgerufen. | ||
. Ein *Änderungsprotokoll-Label* (`changelog:*`) ordnet den _Pull Requests_ in eine der 6 Kategorien ein, in die Änderungen im Änderungsprotokoll gruppiert werden. Wird kein Änderungsprotokoll-Label vergeben, so wird der _Pull Request_ nicht im Änderungsprotokoll erwähnt (kann in Ausnahmesituationen gezielt genutzt werden). | ||
-- | ||
Periodische Releases:: Die Prüfschritte des BITV-Test-Prüfverfahrens werden *in regelmäßigen Abständen* — vorgeschlagen wird ein quartalsweiser oder 2-monatiger Rhythmus — als neues *Release* veröffentlicht. Die Veröffentlichung erfolgt automatisiert über <<githubactions,Github Actions>> und wird durch ein _Scheduler_-Ereignis angestoßen (zeitplanbasiert). Bestandteil eines Releases sind stets alle _Pull Requests_ (und Direktänderungen der Code-Basis) seit der Veröffentlichung des letzten Releases. | ||
Bei Bedarf: Manuelle Releases:: Für Ausnahmesituationen (z. B. bei dringender notwendiger Anpassung) besteht zusätzlich die Möglichkeit, auch außerhalb des regulären Takts manuell Releases zu veröffentlichen. Der eigentliche Vorgang ist mit einem periodischen Release identisch. | ||
[[releaseversion]] | ||
Versionsnummer:: Jedes Release erhält eine eindeutige Versionsnummer nach dem Standard der <<semver,Semantischen Versionierung>>. Zur automatischen Bestimmung der neuen Versionsnummer werden die <<prlabels,Versionierungs-Label>> der im Release erhaltenen _Pull Requests_ betrachtet. Größere Versionssprünge überwiegen kleinere. Das heißt, verlangt ein _Pull Request_ über sein `version:*`-Label eine PATCH-Veränderung, ein anderer dagegen eine MINOR-Veränderung, so wird dies zu einer Anhebung der MINOR-Stelle der Versionsnummer führen (die PATCH-Stelle wird dabei auf 0 zurückgesetzt). | ||
[[releasenotes]] | ||
Automatische Release-Notizen:: Beim Erstellen des Releases werden automatisch Release-Notizen generiert. Es werden sämtliche im Release enthaltenen _Pull Requests_ aufgenommen, die über ein <<prlabels,Änderungsprotokoll-Label>> verfügen. Die einzelnen _Pull Requests_ werden unter Angabe ihres <<prtitle,Titels>>, ihres Autors bzw. ihrer Autorin (verlinktes Github-Handle) sowie der verlinkten Pull-Request-ID dargestellt. Die Einträge werden anhand der Änderungsprotokoll-Label gruppiert. Die Release-Notizen werden durch einen Face-Pile der am Release beteiligten Mitwirkenden abgeschlossen. Beispiele finden sich im link:/tollwerk/BIK-Web-Test/releases[Releases-Bereich dieses Repositories.] | ||
Automatische Aktualisierung des Änderungsprotokolls:: Im Zuge der Release-Erstellung wird auch das Änderungsprotokoll des Repositories aktualisiert. Die Inhalte der <<releasenotes,Release-Notizen>> werden, vom Mitwirkenden-Face-Pile abgesehen, 1:1 ins Änderungsprotokoll übernommen und zusammen mit der <<releaseversion,Release-Version>> und dem Veröffentlichungsdatum wiedergegeben. | ||
Optional: Automatische Release-Assets:: Es ist denkbar, einem Release vor der veröffentlichung <<releaseassets,zusätzliche Assets>> anzuhängen, etwa eine versionierte, dynamisch generierte PDF/UA-Gesamtversion des kompletten Prüfverfahrens mit allen Prüfschritten. | ||
Automatische Release-Folgeaktionen:: Sobald ein Release veröffentlicht wurde, können an dieses Ereignis *weitere Prozessketten* anschließen. Beispielsweise müssen dann die Prüfschrittbeschreibungen im BITV-Test-Studio aktualisiert und auf den neuesten Stand gebracht werden. Es lassen sind jedoch auch viele <<releaseactions,weitere Anschlussaktionen>> denkbar. | ||
|
||
Das dargestellte Release-Konzept ist, von den optionalen Teilen und Vorschlägen abgesehen, in diesem Repository bereits prototypisch umgesetzt, grundsätzlich einsatzfähig und demonstrierbar. | ||
|
||
[NOTE] | ||
Aufgrund eines https://github.com/release-drafter/release-drafter/issues/1148[bekannten Problems] in einem beteiligten Modul kann die Veröffentlichung von Releases derzeit noch nicht vollautomatisch angestoßen werden. Zumal aber ohnehin nur ein quartalsweiser Zeittakt vorgschlagen wird, scheint es zumutbar, die Veröffentlichung von Releases bis zur Behebung des Problems manuell anzustoßen. | ||
|
||
[[pullrequesttitel]] | ||
=== Pull-Request-Titel [TBD] | ||
|
||
Es ist eine Richtlinie für das Verfassen von Pull-Request-Titeln zu entwickeln. | ||
|
||
[[releaseassets]] | ||
=== Releases-Assets [TBD] | ||
|
||
Die folgenden Assets könnten bei der Veröffentlichung eines Releases erzeugt und angehängt werden: | ||
|
||
- [ ] PDF/UA-Gesamtausgabe des Prüfverfahrens (siehe <<releaseactions,Release-Aktionen>>) | ||
|
||
[[releaseactions]] | ||
=== Release-Aktionen [TBD] | ||
|
||
Die folgenden Prozessketten könnten / sollten sich an das Veröffentlichen eines neuen Releases (automatisiert) anschließen. | ||
|
||
- [x] Aktualisieren der Prüfschrittbeschreibungen im BITV-Test-Studio (bereits implementiert) | ||
- [ ] Aktualisieren der Prüfschrittbeschreibungen auf der zukünftigen Microsite (vorbereitet) | ||
- [ ] Erzeugen und Archivieren einer PDF/UA-Gesamtausgabe des Prüfverfahrens auf der Microsite (zur Verlinkung in Prüfberichten u.ä.) | ||
- [ ] Erzeugen eines News-Beitrags auf der Microsite (mit Inhalt der Release-Notizen) | ||
- [ ] Erzeugen eines RSS-Feed-Eintrags (Microsite?) zur Darstellung im BITV-Test-Studio | ||
- [ ] Versand eines E-Mail-Newsletters and die Prüfer-Mailingliste | ||
|
||
== Fragestellungen | ||
- Müssen die Prüfschrittbeschreibungen im Studio versioniert vorliegen, so dass zu jedem Prüfauftrag initial die Versionsnummer des Verfahrens gesichert wird und dann stets die Prüfschrittbeschreibungen dieser Version angezeigt werden? Wieviel Aufwand soll hier betrieben werden? |
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.