A. Prozessdokumentation
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.
- 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
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.
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.
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.
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.
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
Deployments finden Mo-Fr statt. Aufgrund der Analyse der Besuchendenzahlen finden Deployemnts am Vorabend, nach 16 Uhr statt. 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.
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 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.
Für das Installieren grosser Decidim-Updates muss erfahrungsgemäss einiges an Zeit reserviert werden, da alle grösseren, Zürich-spezifischen Änderungen überprüft werden müsse. Wir handeln nach folgendem Schema:
- Einplanen grösserer Updates in die Jahresplanung. Die Releases werden von Decidim frühzeitig kommuniziert und können somit in die Planung einfliessen. Grundsätzlich besteht je ein Release-Termin im Frühling (ca. Ende März) und im Herbst (ca. Oktober/November).
- Ist der Release da, müssen die Änderungen durch den PO und den technischen Dienstleister abgeschätzt und eine Aufwandsschätzung für das Update erarbeitet werden. Der technische Dienstleister soll versuchen zu erkennen, welche Änderungen besonders zeitaufwändig bzw. Implikationen für die bereits durchgeführten Anpassungen der Zürcher Plattform mit sich bringen.
- Abwarten Aktualisierungen der Module. Als nächstes muss abgewartet werden, bis die Module (z.B. Decidim Awesome und der Term Customizer) ebenfalls auf die neue Decidim-Version gebracht werden.
- Dieser Zeitraum soll genutzt werden, um Erfahrungsberichte von Plattformen einzuholen, die das Update bereits durchgeführt haben und dauert erfahrungsgemäss min. 3 Monate.
- Sind die Drittmodule auf einem aktuellen Stand, kann mit den eigentlichen Update-Arbeiten begonnen werden. In Absprache mit dem Projektteam und der STEZ wird das Update auf die INT ausgerollt.
- Auf der INT wird das Update ausführlich getestet und grössere Änderungen dokumentiert (bspw. im Update-Blog, Anpassung der Manuals). Bei schwerwiegenden Änderungen werden die prozessdurchführende Personen informiert (z.B. per Plattform-Newsletter)
- In Absprache mit allen auf der Plattform laufenden Prozess wird ein geeigneter Termin für einen Prod-Release geplant (siehe A.1).
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.
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:
- einer Eingabe direkt auf Crowdin (kommt allen Decidim Usern zu Gute)
- durch eine der nachfolgenden Ebenen (prioritär bei diesem Projekt).
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.
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.
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.
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.
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.
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.
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"
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.
Mittels Decidim Awesome können URL-Weiterleitungen eingerichtet werden. Das ist hilfreich, wenn z.B. kürzere und einfach merkbare URLs für die Kommunikation verwendet werden müssen. Ein grosser Vorteil ist, dass die generierten Weiterleitungen aktualisiert werden können und so ein Link für die Kommunikation erstellt werden kann (z.B. mitwirken.stadt-zuerich.ch/umfrage) und dieser angepasst werden kann sollte sich an der Ziel-URL etwas ändern. Das ist nützlich, wenn im Prozess beispielsweise eine neue Komponenten verwendet wird, welche auch eine neue URL besitzt.
Hinweis: Dieser Eintrag behandelt die ab Decidim V0.26 neu eingeführte Erweiterung von Decidim Awesome. Das in früheren Versionen verwendete Modul «URL Aliases» funktioniert aber beinahe gleich.
URL Weiterleitungen können nur von Plattformadmins eingerichtet werden.
- In Decidim Awesome auf «Benutzerdefinierte Weiterleitungen» klicken.
- Auf «Neue Umleitung» klicken
- Unter «Origin» die gewünschte, neu zu erstellende URL eintragen. Einzutragen sind absolute Pfade, d.h. der Teil, der nach der Domain folgt. Wenn als
mitwirken.stadt-zuerich.ch/umfrageeingerichtet werden soll, muss/umfrageeingetragen werden. - Unter «Destination» die gewünschte Zielseite eintragen. Diese Seite muss bereits bestehen.
- Wenn «Active» angekreuzt ist, läuft die Weiterleitung.
- Weiterleitung sichern. Ein Click auf «Umleitungen prüfen» überprüft, ob die Umleitungen wie gewünscht funktionieren.
- Als Origin darf keine bereits bestehende Seite angegeben werden. Dies deshalb, weil die Seite sonst missbräulich verwendet werden kann.
- Jeder Origin darf nur einmal vorkommen.
- Die Option «Pass Query» kann weiterführende Informationen weiterleiten. Beispiel: Wenn über die Analytics erhoben werden soll, wie viele Besuchende ein Plakat QR-Code generiert, kann eine Query eingerichtet werden. Dies erfordert jedoch weiterführende Konfigurationen.
folgt
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.
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 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
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
Abgeschlossene Prozesse bringen einige letzte Änderungen mit sich, wir reden dabei zuerst vom «Einfrieren», dem unterbinden einer weiteren Beteiligung, und am Schluss vom «Archivieren» eines Prozesses.
Ein Prozess kann archiviert werden, wenn die Verantwortliche Organisationseinheit bzw. die Projektleitenden dafür das OK geben. Meist ist dies der Fall, wenn das Gesamtprojekt, in dessen Rahmen die Partizipation durchgeführt wurde, abgeschlossen ist und ein Endresultat, z.B. ein Schlussbericht zum Partizipationsprozess verfügbar ist. Folgende Massnahmen müssen getroffen werden:
- Alle generierten Daten (z.B. Umfrageergebnisse) können durch die Projektverantwortlichen heruntergeladen werden (CSV, Excel, PDF) und im Rahmen des Gesamtprojektes archiviert werden.
- Der Schlussbericht soll hochgeladen und ein Link auf das Projekt in der städtischen Website aufgenommen werden. Auf der Plattform werden anschliessend alle generierten Daten so weit möglich gelöscht.
- Die Veröffentlichung aller Prozesskomponenten ist zurückzuziehen, so dass nur noch die Übersichtsseite da steht.
- Die Komponenten sollen, wenn möglich, gelöscht werden. Ansonsten bleiben sie einfach unveröffentlicht.
- Im Term Customizer ist im Set
Mitwirken_prod_abgeschlosseneProzesseeine Einschränkung (mittels Klick auf das Stift-Symbol) auf den abzuschliessenden Prozess zu erstellen.
- Auf Decidim Awesome unter "Eigene Styles" ist eine Einschränkung für den Prozess für die Grafik-Gruppe
proc_archivierteprozesseauszuwählen.