Skip to content

A. Prozessdokumentation

Lars Kaiser edited this page Jan 11, 2023 · 8 revisions

A.1 Github-Workflow

Wir arbeiten Ticket-basiert unter Projects - «Umsetzung 2022» (für «Mitwirken an Zürichs Zukunft») und «Quartierplattform». Der Workflow eines Tickets (auch Issue genannt) verläuft durch die folgenden Spalten von links nach rechts.

Hinweis: Vielen Dank an die Stadt Luzern, von denen wir diese Prozessdokumentation übernehmen und anpassen durften.

Allgemeine Regeln

  • Bei priorisierten Spalten haben die Issues zuoberst immer die höchste Priorität
  • Wenn Antwort erwartet wird, ist das Issue der entsprechenden Person zuzuweisen
  • Wer zuletzt an einem Issue arbeitet, stellt sicher, dass das Issue in der richtigen Spalte ist

Spalten

Backlog

In dieser Spalte werden Ideen als Issue festgehalten, welche noch nicht für die Umsetzung im Rahmen des Budgets 2022 entschieden sind oder deren Ausführungsgrad noch nicht soweit ist, dass am Ticket gearbeitet werden könnte. Der Backlog ist nicht priorisiert.

Ready

Ein Issue in dieser Spalte soll umgesetzt werden. Die Spalte ist priorisiert.

Developer Workflow: Wir nehmen uns nach Rücksprache am wöchentlichen Standup die obersten Issues vor. Wir bewegen das Ticket woran wir momentan Arbeiten nach In Progress.

In progress

Wird ein Issue durch einen Entwickler umgesetzt, wird es in diese Spalte verschoben. Zudem wird die Person, die daran arbeitet, als Assignees zugewiesen (damit auf einen Blick ersichtlich ist, wer an was arbeitet). Die Zuweisung erfolgt in der Regel am Weekly Standup Meeting.

Developer Workflow: Wenn man fertig ist mit der Arbeit an einem Ticket, schliesst man es und verschiebt es nach Review. Dies ist automatisiert möglich, per commit oder PR.

Review

Jedes Ticket wird nach der Umsetzung durch eine zweite Person geprüft, getestet und Feedback gegeben. Zudem können in dieser Spalte auch Tickets abgelegt werden, bei denen eine Antwort ausstehend ist.

Developer Workflow: Das Ticket wird der/den gewünschten Person/en zugewiesen, die das Ticket reviewen soll/en. Nach einem Deployment auf der Integration wird ein Ticket nach Testable on Integration verschoben.

Testable on Integration

Hier befinden sich Tickets, die umgesetzt wurden und auf der Integrationsumgebung getestet werden können. Sobald die Auftraggeberin das OK gibt, wird das Ticket auf die Produktionsumgebung deployed. Das OK erfolgt in Form eines kurzen Textes. Beim Deployment auf die Produktion prüft die Auftragnehmerin, dass die Issues OK sind und fragt gegebenenfalls nach, falls noch kein Feedback vorliegt.

Developer Workflow: Nach einem Deployment auf der Produktion wird ein Ticket nach Deployed on Production verschoben. Notiz: Ein Ticket wird per Text als ok dokumentiert und mit dem Tag "ready for production" markiert und somit gut sichtbar.

Vorschlag: Ein Label namens ready for production

Deployment on Production

Deployments finden Mo-Fr statt. Auf Empfehlung von Puzzle nutzen wir hierfür die Mittagszeit, 12:00 bis 13:00 Uhr. Wenn etwas geplant auf die Produktion deployed werden soll, wird dies spätestens am Vortag gemeinsam zwischen der Stadt Zürich (Co-Projektleitung) und Puzzle ([email protected], oder mit ScrumMaster oder mit demjenigen Dev, der für den Release arbeitet) festgelegt. Um die Anwender*innen zu informieren, wird zusätzlich im Header gut sichtbar von «Mitwirken an Zürichs Zukunft» UND «MeinQuartier.zuerich» eine Ankündigung in den 24h davor gemacht inkl. den wichtigsten Infos zum Update (einfache Release Notes mit allenfalls weitergehenden Infos z.B. im Falle eines Decidim-Updates, geführt als neue Page im Partizipationsprozess "Mitwirken an «Mitwirken an Zürichs Zukunft»").

Im Falle von dringenden Updates ebenfalls in gegenseitiger Abstimmung, jedoch ohne Vorankündigung und ohne einem Tag Vorlaufzeit.

Anschliessend werden die Tickets in die Spalte "Done" verschoben.

Done

Hier befinden sich alle erledigten Tickets. Issues initiiert durch die Auftraggeberin werden von ihr in diese Spalte geschoben. Analog werden Issues von der Auftragnehmerin nach Done verschoben, wenn erledigt.

Labels

Labels werden verwendet, um gewisse Zustände oder Bedürfnisse eines Tickets zu signalisieren. Folgende Labels werden verwendet:

bug Etwas läuft nicht wie gewünscht. Bugs treten meistens im produktiven Betrieb auf und sollten schnell geflickt werden.

discussion Themen, meistens in der Backlog-Spalte, zu denen das Vorgehen noch nicht ganz klar ist. Inputs von allen Lesenden erwünscht.

CI/CD Grafische Anpassung, meistens CSS.

update Tickets mit Bezug zu grossen Versionsupdates

enhancement Ein Feature, das in bedeutenden Merkmalen vom Core abweicht. Diese Features werden mit einem Eintrag im Github-Wiki unter Kapitel 4 – Weiterentwicklungen beschrieben.


A.2 Umgang mit Spam-Accounts

Decidim sieht sich leider seit Ende 2021 einer regelrechten Spam-Welle konfrontiert. Viele Accounts sind harmlos und schaffen einfach ein Profil, andere spammen die Kommentarspalte zu. Reine Werbeprofile sind für die Plattform nicht kritisch, da sie nur dann aufgerufen werden können, wenn explizit nach Ihnen gesucht wird. Bei Accounts hingegen besteht die Gefahr, dass durch die geposteten Beiträge Menschen auf Phishing-Seiten o.ä. weitergeleitet werden. Hier ist es wichtig, möglichst schnell zu reagieren und die Beiträge zu verbergen.

Update 2022: Mittels Captcha wurde die Registrierung erschwert.

Beiträge verbergen

Treten Spam-Beiträge auf, so müssen diese möglichst schnell im Frontend per Click auf das Fähnchen-Icon nebst dem Beitrag/Vorschlag/Nutzenden gemeldet werden. Alle Plattformadmins/moderatoren werden direkt per Mail benachrichtigt und können im Backend unter dem Reiter "Globale Moderationen" den Beitrag verbergen.

WICHTIG: Nicht nur den Beitrag melden, sondern gleich den Nutzenden blockieren!

Nutzende blockieren

Nutzende können im Backend unter «Benutzer» > Teilnehmer verwaltet werden. Ein Nutzer kann per Click auf das entsprechende Symbol und Angabe einer Begründung gesperrt werden, bspw. mit:

Guten Tag, Wir werten Ihr Konto als Spam-Konto. Es wird deshalb blockiert. Falls Sie sich unrecht behandelt fühlen, kontaktieren Sie uns bitte via Kontaktformular. Freundliche Grüsse, das «Mitwirken an Zürichs Zukunft»-Team

Massenhaftes Blockieren

Ab und an lohnt es sich, eine gründliche Suche nach Spam-Accounts zu machen und diese zu löschen. Als «Trick» empfiehlt es sich hier, nach Keywords zu suchen, die die Spam-Accounts häufig im Namen haben. Eine Auswahl: casino, bet, cash, blog, escort, soccer, football, stream, gaming, merch, slots, crypto, coin Somit können Accounts effizient gefunden und blockiert werden


A.3 Sprachfiles & Term-Customizer-Konventionen

Sprachfiles werden von Decidim direkt in den Code eingebaut. Je nach Tenant/Prozess müssen einzelne Begriffe spezifisch angepasst werden. Hier kommt der Term-Customizer ins Spiel. Um über alle Tenants einen möglichst gleichmässigen Übersetzungsstand und Übersichtlichkeit zu garantieren, wird hier eine Konvention definiert. Sie erstreckt sich von System- bis hinunter zur Prozessebene.

Top-Level: Crowdin-Sprachfile

Das Grundsprachfile ist das Crowdin-Sprachfile, welches standardmässig mit Decidim kommt und von der Meta Decidim Community verwaltet wird. Es kann (und sollte nicht) über dieses Projekt verändert werden, sondern entweder durch:

  1. einer Eingabe direkt auf Crowdin (kommt allen Decidim Usern zu Gute)
  2. durch eine der nachfolgenden Ebenen (prioritär bei diesem Projekt).

Second-Level: Decidim Sprachfile

Das Sprachfile umfasst die Grundbegriffe Decidims und wird direkt im File, d.h. im Code und nicht über Decidim, angepasst. Das wird automatisch für alle Tenants übernommen. Deshalb sollte das Sprachfile die absolut essenziellen Begriffe, welche für alle Plattformen gleich benutzt werden, aufführen. Es sollte, auch aufgrund möglicher schwerwiegender Auswirkungen auf die Plattform, so selten wie möglich angepasst werden (z.B. wenn nach einem neuen Decidim Update Übersetzungen fehlen bzw. aktualisiert werden müssen). Das Sprachfile bildet die Grundlage der Überschreibungen durch den Term-Customizer.

Sprachfile bearbeiten

Das Sprachfile kann direkt über Github angepasst werden. Es befindet sich im Ordner config>locales>de.yml (Deutsch) Vorsicht: Eine fehlerhafte Bearbeitung des Sprachfiles (z.B. Auslassen eines Anführungszeichens) kann folgenschwere Konsequenzen für die Plattform haben, beispielsweise dass die betroffenen Seiten nicht mehr geladen werden können. Deshalb sollten die Änderung vor einem Merge jeweils überprüft werden.

Third-Level: Term-Customizer

Alle weiteren Übersetzungen (Grundübersetzungen, Tenant- und Prozessanpassungen) können mit dem Plugin Term-Customizer im Decidim-Backend bearbeitet werden. Der Term-Customizer funktioniert so, dass Sammlungen von übersetzten Begriffen (Translation Sets) erstellt werden, welche dann entweder auf die ganze Plattform oder nur für einzelne Prozesse/Organisationen/Komponenten usw. Anwendung finden (Scoping). Somit entstehen zahlreiche Sets, die sich teilweise gegenseitig überschreiben (z.B. wenn ein Set für die ganze Plattform und eines nur für einen Prozess denselben Begriff übersetzen), und es ist wichtig, hier eine Übersicht zu behalten. Nachfolgend wird eine Konvention definiert, die dem Term-Customizer eine bedienungsfreundliche Struktur verschaffen soll. Die Idee ist, dass die Set-Titel jeweils die Anwendungsstufe beinhalten und somit die Sets nach Anwendungsebene gruppieren. Zuoberst sollen die Grundübersetzungssets und zuunterst die Prozess/Komponentenabhängige Sets erscheinen.

Tenantübergreifende Übersetzungen

Decidim listet nicht alle Grundübersetzungen im Sprachfile auf und verwendet teilweise fehlerhafte übersetzte Begriffe. Deshalb sind auch hier Anpassungen notwendig. Diese Übersetzungen sollen auf allen Plattformen den gleichen Stand aufweisen. Aus diesem Grund werden die jeweils aktuellen Grundübersetzungen als .Zip hier hochgeladen und können so auf Quartier- und Mitwirken-Plattform in der Int- und Prod-Umgebungen importiert werden.

Konvention Bezeichnung als admin_Setname.
Beispiel: admin_Veranstaltungen -> Bezeichnet das Set der angepassten Begriffe in der Vorschlagskomponente.

Download Hier können die aktuellen Sets heruntergeladen werden: Download (Stand 7.01.22)
Falls Anpassungen an diesen Sets für alle Plattformen vorgenommen werden, bitte erneut hochladen. Ansonsten Begriffe mit eigenen Sets überschreiben.

Tenantspezifische Übersetzungen

Gewisse Sets gelten für die ganze Plattform (Mitwirken- oder Quartierplattform), sowohl für die Integrations- als auch für die Produktionsumgebung

Konvention Bezeichnung mit Plattformnamen.
Beispiel: mitwirken_mailer -> Bezeichnet Anpassungen an den versendeten Mail-Benachrichtigungen auf der «Mitwirken an Zürichs Zukunft» Plattform.

Integrations- und produktionsabhängige Übersetzungen

Gewisse Sets gelten ausschliesslich für die Integrations oder Produktionsumgebung eines Tenants.

Konvention Bezeichnung mit Names des Tenants und _int oder _prod.
Beispiel: mitwirken_int_hilfeseite -> Bezeichnet Anpassungen an der Hilfeseite der Integrationsumgebung uf der «Mitwirken an Zürichs Zukunft» Plattform.

Prozess- bzw. organisationsabhängige Übersetzungen

Bezeichnet Anpassungen die nur auf dieser Plattform gemacht werden.

Konvention Bezeichnung mit x_type_name. Falls innerhalb eines Prozesses/einer Organisation noch gescoped wird, wird die Komponente dem Prozess/der Organisation angehängt.
Beispiele:

  • x_prozess_Stadtidee: Anpassungen am Prozess "Stadtidee"
  • x_prozess_Stadtidee_Budget: Anpassungen am Budgetmodul im Prozess "Stadtidee"
  • x_organisation_QVwiedikon: Anpassungen an der Organisation "QV Wiedikon"

Nicht (mehr) verwendete Translation Sets

Nach abgeschlossenen Prozessen bzw. bei nicht mehr verwendeten Organisationen können die Term-Customizer Sets entweder gelöscht werden, oder archiviert werden, etwa wenn der Prozess noch im Backend ersichtlich bleibt. Es kann auch sein, dass ein Set vorübergehend nicht verwendet wird und "auf die Seite geschoben" werden muss. In diesem Fall ist es wichtig, dass der Scope auf eine unveröffentlichte Komponente zeigt. Konvention

  • Nicht mehr verwendet: z_ARCHIVIERT_Prozessname
  • Vorübergehend nicht verwendet: z_NICHTVERWENDET_Prozessname

##Hierarchien Standardmässig wird das Crowdin-Sprachfile als Basis genommen und regelmässig bei Updates gepflegt. Dieses wird dann in erster Folge vom Sprachfile überschrieben, dort wo zu überschreibende Keys vorhanden sind. Als letztes folgt dann der Term-Customizer, welcher wiederum alle Begriffe überschreiben kann.

Clone this wiki locally