From 8fb1560ec57503108f3cec6316879f7d144cca66 Mon Sep 17 00:00:00 2001 From: Joschi Kuphal Date: Sat, 18 Jun 2022 21:20:01 +0200 Subject: [PATCH 1/5] Starte Konzept-Dokumentation --- README.adoc | 77 +++++++++++++++++++++++++++++++++++++++++++++++++ convert2html.rb | 37 ------------------------ readme.adoc | 19 ------------ 3 files changed, 77 insertions(+), 56 deletions(-) create mode 100644 README.adoc delete mode 100644 convert2html.rb delete mode 100644 readme.adoc diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..ed60006 --- /dev/null +++ b/README.adoc @@ -0,0 +1,77 @@ += BIK BITV-Test Release-Konzept +:author: Joschi Kuphal +:email: joschi@tollwerk.de +: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 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; <>). + +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. diff --git a/convert2html.rb b/convert2html.rb deleted file mode 100644 index 849086f..0000000 --- a/convert2html.rb +++ /dev/null @@ -1,37 +0,0 @@ -require "asciidoctor" -require "optparse" -flags = {} -adoc_attributes = {} -source_dir = "Prüfschritte/de" -theme_name = "theme" -src_theme_dir = source_dir + "/" +theme_name -output_dir = "html/de" -out_theme_dir = output_dir + "/" + theme_name -OptionParser.new do |opts| - opts.on('-s', '--standalone') -end.parse!(into: flags) -if File.directory?(source_dir) then - Dir[source_dir + "/*.adoc"].each { |adoc_fn| - if flags[:standalone] then - adoc_attributes["env_embedded"] = false - else - adoc_attributes["env_embedded"] = true - end - Asciidoctor.convert_file( - adoc_fn, to_dir:output_dir, safe:"safe", mkdirs:true, - header_footer:flags[:standalone], attributes:adoc_attributes - ) - } - if flags[:standalone] && File.directory?(src_theme_dir) then - if !File.directory?(out_theme_dir) then - Dir.mkdir(out_theme_dir) - end - Dir[src_theme_dir + '/*.{css,js}'].each {|theme_file| - data = IO.read(theme_file) - target_fd = File.open(out_theme_dir + "/" + File.basename( - theme_file), "wb") - target_fd.write(data) - target_fd.close() - } - end -end \ No newline at end of file diff --git a/readme.adoc b/readme.adoc deleted file mode 100644 index 437e57a..0000000 --- a/readme.adoc +++ /dev/null @@ -1,19 +0,0 @@ -= BIK BITV-Test (Web) -DIAS GmbH -2020-04-16 -:lang: de - -In diesem Projekt werden Prüfschritte des https://bitvtest.de[BIK BITV-Tests (Web)] für die Barrierefreiheit von Webseiten -entwickelt. Neue Meilenstein-Versionen werden bei Bedarf, spätestens quartalsweise festgesetzt. - -Die zugrunde liegenden Kriterien richten sich nach der aktuell veröffentlichen https://www.etsi.org/deliver/etsi_en/301500_301599/301549/03.02.01_60/en_301549v030201p.pdf[EU Norm 301 549 V3.2.1 (PDF)]. - -* link:Prüfschritte/de/[Zu den Prüfschritten] - -Die Prüfschritte sind in der Auszeichnungssprache AsciiDoc verfasst. Um die -Mitarbeit zu unterstützen, stellen wir ein Tutorial für den Schnelleinstieg -bereit. -Orientieren Sie sich bei der Gestaltung des Quelltextes (Einrückungen etc.) -an der Art und Weise, die Sie vorfinden. - -* https://github.com/BIK-BITV/BIK-App-Test/blob/master/support/AsciiDoc/AsciiDoc%20Tutorial.adoc[Zum AsciiDoc Tutorial] From e8a292cea18f725e81a38391c10794965af84838 Mon Sep 17 00:00:00 2001 From: Joschi Kuphal Date: Sat, 18 Jun 2022 21:51:58 +0200 Subject: [PATCH 2/5] =?UTF-8?q?Erg=C3=A4nze=20Pull-Requests?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.adoc | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/README.adoc b/README.adoc index ed60006..936bfe8 100644 --- a/README.adoc +++ b/README.adoc @@ -34,7 +34,7 @@ Darüber hinaus enthält das Repository eine Kopie der Prüfschritte des BITV-Te == Tools & Standards -Die folgenden Abschnitte stellen verschiedenen Github-Konzepte und -Funktionalitäten sowie sinnvolle Standards vor, aus denen schließlich ein Vorgehensvorschlag modelliert wird. +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 @@ -75,3 +75,14 @@ Der https://keepachangelog.com[Keep a Changelog]-Standard setz sich für das kon - 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. + +=== 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 besonders hohen Vertrauensstellung und mit viel Erfahrung vorbehalten sein. Im Idealfall wird durch entsprechende Einstellungen dafür gesorgt, dass eine direkte Veränderung der Code-Basis nicht möglich ist. From 3240603f3fae50c95777f7aafb95968296cb59ae Mon Sep 17 00:00:00 2001 From: Joschi Kuphal Date: Sat, 18 Jun 2022 21:57:30 +0200 Subject: [PATCH 3/5] =?UTF-8?q?Erg=C3=A4nze=20Labels?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.adoc | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/README.adoc b/README.adoc index 936bfe8..fb2c2c4 100644 --- a/README.adoc +++ b/README.adoc @@ -76,6 +76,7 @@ Der https://keepachangelog.com[Keep a Changelog]-Standard setz sich für das kon - 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_. @@ -85,4 +86,8 @@ Beim BITV-Test-Prüfverfahren stellen _Pull Requests_ den Standard-Weg dar, auf 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 besonders hohen Vertrauensstellung und mit viel Erfahrung vorbehalten sein. Im Idealfall wird durch entsprechende Einstellungen dafür gesorgt, dass eine direkte Veränderung der Code-Basis nicht möglich ist. +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 <> 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. From 68c52200e52abd517a97f31469562e6a25bd03a0 Mon Sep 17 00:00:00 2001 From: Joschi Kuphal Date: Sat, 18 Jun 2022 22:08:50 +0200 Subject: [PATCH 4/5] =?UTF-8?q?Erg=C3=A4nze=20Github-Actions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.adoc | 42 +++++++++++++++++++++++++++++++++--------- 1 file changed, 33 insertions(+), 9 deletions(-) diff --git a/README.adoc b/README.adoc index fb2c2c4..a99a66e 100644 --- a/README.adoc +++ b/README.adoc @@ -43,7 +43,8 @@ Der betreffende Repository-Stand ist dann anhand dieses Tags eindeutig referenzi 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; <>). -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: +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. @@ -51,7 +52,8 @@ Github als Community-Plattform bietet zusätzlich die Möglichkeit, getaggte St [[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). +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] ---- @@ -70,24 +72,46 @@ PATCH:: wird erhöht, wenn die Änderungen ausschließlich API-kompatible Bugfix [[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: +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. +- 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_. +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). +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. +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. +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 <> 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. +Um die Bearbeitungsabläufe benutzerfreundlich zu gestalten, bietet Github an, _Issues_ und <> 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. + +=== 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. From be9e8b4086ba611083e9465a9eef92da02861eec Mon Sep 17 00:00:00 2001 From: Joschi Kuphal Date: Sat, 18 Jun 2022 23:30:24 +0200 Subject: [PATCH 5/5] =?UTF-8?q?Schlie=C3=9Fe=20ersten=20Entwurf=20ab?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.adoc | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/README.adoc b/README.adoc index a99a66e..589efa8 100644 --- a/README.adoc +++ b/README.adoc @@ -107,6 +107,7 @@ Um die Bearbeitungsabläufe benutzerfreundlich zu gestalten, bietet Github an, _ 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. @@ -115,3 +116,59 @@ Oder es können beim Veröffentlichen eines Releases Kompilierschritte vollzogen _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 <>* 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 <> 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 <> 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 <>. Zur automatischen Bestimmung der neuen Versionsnummer werden die <> 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 <> verfügen. Die einzelnen _Pull Requests_ werden unter Angabe ihres <>, 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 <> werden, vom Mitwirkenden-Face-Pile abgesehen, 1:1 ins Änderungsprotokoll übernommen und zusammen mit der <> und dem Veröffentlichungsdatum wiedergegeben. +Optional: Automatische Release-Assets:: Es ist denkbar, einem Release vor der veröffentlichung <> 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 <> 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 [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?