[ English | Indonesia | 한국어 (대한민국) | русский | Deutsch | English (United Kingdom) | français ]

Code Regeln

Allgemeine Richtlinien für die Einreichung von Code

  • Schreiben Sie gute Commit-Nachrichten. Wir folgen dem OpenStack-Leitfaden „Git Commit Good Practice“. Wenn Sie Fragen zum Schreiben von Gute-Commit-Nachrichten haben, lesen Sie die Upstream-Dokumentation.

  • Änderungen am Projekt sollten über das Gerrit-Tool nach dem zur Überprüfung eingereicht werden. workflow documented here.

  • Pull-Anfragen, die über GitHub gesendet werden, werden ignoriert und ohne Rücksicht geschlossen.

  • Patches sollten sich darauf konzentrieren, ein Problem auf einmal zu lösen. Wenn die Rezension zu komplex oder allgemein zu groß ist, erhält die initiale Festschreibung eine **-2**, und der Beitragende wird aufgefordert, den Patch auf mehrere Überprüfungen aufzuteilen. Bei komplexen Feature-Ergänzungen sollte das Design und die Implementierung des Features so gestaltet werden, dass es in mehreren Patches über Abhängigkeiten übergeben werden kann. Die Verwendung abhängiger Änderungen sollte immer darauf abzielen, zu einem funktionierenden Build in der gesamten Abhängigkeitskette zu führen. Die Dokumentation steht auch in advanced gerrit usage zur Verfügung.

  • Alle Patch-Sets sollten sich an den hier aufgelisteten Ansible-Stil Anleitung halten und, wenn möglich, den Ansible best practices folgen.

  • Alle Änderungen sollten in der Commit-Nachricht mit einer zugehörigen Bug-ID/Blueprint zusammen mit zusätzlichen Informationen klar aufgeführt werden, wo zutreffend.

  • Refactoring-Arbeiten sollten niemals zusätzliche Rider -Funktionen enthalten. Funktionen, die sich auf etwas beziehen können, das neu strukturiert wurde, sollten als Problem behandelt und in vorherigen oder nachfolgenden Patches eingereicht werden.

  • Neue Features, brechende Änderungen und andere Notizfelder müssen eine Release-Note enthalten, die mit dem the reno tool erzeugt wurde. Bitte beachten Sie die Documentation and Release Note Guideline für mehr Informationen.

  • Alle Patches einschließlich Code, Dokumentation und Versionshinweise sollten vor dem Einreichen zur Überprüfung lokal mit der entsprechenden Testsuite erstellt und getestet werden. Siehe Development and Testing für mehr Informationen.

Dokumentation und Release Note Richtlinien

Die Dokumentation ist ein wichtiger Bestandteil, um sicherzustellen, dass die Implementierer von OpenStack-Ansible angemessen über Folgendes informiert sind:

  • So verwenden Sie die Tools des Projekts effektiv zum Bereitstellen von OpenStack.

  • Wie man die richtige Konfiguration implementiert, um die Anforderungen ihres spezifischen Anwendungsfalles zu erfüllen.

  • Änderungen im Projekt im Laufe der Zeit, die sich auf eine vorhandene Bereitstellung auswirken können.

Um diese Anforderungen zu erfüllen, müssen Entwickler Folgendes einreichen code comments, Dokumentation (siehe auch Abschnitt documentation locations section) und release notes mit irgendwelchen Code-Einreichungen.

Alle Arten von Dokumentationen sollten den Richtlinien im OpenStack Documentation Contributor Guide entsprechen, mit besonderem Bezug auf die folgenden Abschnitte:

  • Schreibstil

  • RST-Formatierungskonventionen

Code Kommentare

Code-Kommentare für Variablen sollten verwendet werden, um den Zweck der Variablen zu erklären. Dies ist besonders wichtig für die Datei mit den Rollenvorgaben, da die Datei in der Dokumentation der Rolle wortwörtlich eingefügt wird. Wenn eine optionale Variable vorhanden ist, sollte die Variable und eine Erläuterung, wofür sie verwendet wird, zur Standarddatei hinzugefügt werden.

Code-Kommentare für Bash/Python-Skripte sollten Hinweise für den Zweck des Codes geben. Dies ist wichtig, um den Prüfern einen Kontext zu bieten, bevor der Patch zusammengeführt wurde, und um später für spätere Änderungen daran zu erinnern, was der Zweck war und warum es so gemacht wurde.

Dokumentationsstandorte

OpenStack-Ansible verfügt über verschiedene Formen der Dokumentation mit unterschiedlichen Absichten.

Der Deployment Guide beabsichtigt, den Bereitstellern zu helfen, OpenStack-Ansible zum ersten Mal bereitzustellen.

Das Benutzerhandbuch beabsichtigt, Benutzer Informationen darüber bereitzustellen, wie bestimmte Dinge mit OpenStack-Ansible durchgeführt werden können.

Das Betriebshandbuch gibt Hilfestellung bei der Verwaltung und dem Betrieb von OpenStack-Ansible.

Die ausführliche technische Information befindet sich in der OpenStack-Ansible Reference.

Die Rollendokumentation (z. B. die Keystone-Rollendokumentation) erläutert alle für die Rolle verfügbaren Optionen und erläutert, wie erweiterte Anforderungen implementiert werden. Um Doppelarbeit zu vermeiden, enthält die Rollendokumentation direkt die Standardvariablendatei der Rolle, die die Kommentare enthält, die den Zweck der Variablen erläutern. Die Volldokumentation für die Rollen sollte sich weniger auf das Erläutern von Variablen als auf die Erläuterung der Implementierung von erweiterten Anwendungsfällen konzentrieren.

Die Rollendokumentation muss eine Beschreibung der obligatorischen Infrastruktur (z.B. eine Datenbank und eine Nachrichtenwarteschlange), Variablen (z.B. den Datenbanknamen und Anmeldeinformationen) und Gruppennamen (z.B. die Rolle erwartet eine Gruppe mit dem Namen) enthalten foo_all ist vorhanden und erwartet, dass der Host ein Mitglied davon ist), damit die Ausführung der Rolle erfolgreich ist.

Wo immer möglich, sollte die Dokumentation in OpenStack-Ansible nicht versuchen, OpenStack-Konzepte zu erklären. Diese Erläuterungen gehören in die OpenStack-Handbücher oder die Servicedokumentation, und die OpenStack-Ansible-Dokumentation sollte, wenn verfügbar, mit diesen Dokumenten verknüpft werden, anstatt deren Inhalt zu duplizieren.

Versionshinweise

Versionshinweise werden mit dem the reno tool erzeugt. Versionshinweise müssen unter Berücksichtigung der folgenden Richtlinien erstellt werden:

  • Jedes Listenelement muss ohne den Kontext des Patches oder des Repositorys, in das der Patch gesendet wird, gelesen werden. Der Grund dafür ist, dass alle Versionshinweise konsolidiert und in einer langen Liste ohne Verweis auf den Quell-Patch oder den Kontext des Repositorys präsentiert werden.

  • Jede Note sollte kurz und bündig sein. Versuchen Sie, Mehrfachabsatznotizen zu vermeiden. Bei Features sollte die Notiz in der Regel für weitere Details auf die Dokumentation verweisen. Für Fehlerbehebungen kann die Notiz für mehr Details auf einen registrierten Fehler verweisen.

In den meisten Fällen sollten nur die folgenden Abschnitte für neue Release Notes verwendet werden, die mit Patches eingereicht wurden:

  • features: Dies sollte den Deployer kurz über ein neues Feature informieren und sollte beschreiben, wie man es verwendet, indem man entweder auf die Variablen verweist oder auf die Dokumentation verweist.

  • issues: Dies sollte den Deployer über bekannte Probleme informieren. Dies kann verwendet werden, wenn ein Problem behoben wird und die Bereitsteller über eine Problemumgehung informiert werden sollen, die für frühere Versionen verwendet werden kann, die den Patch enthalten, der das Problem behebt. In den Notizen sollte speziell erwähnt werden, welche Versionen von OpenStack-Ansible von dem Problem betroffen sind.

  • upgrade: Dies sollte den Deployer über Änderungen informieren, die sie beim Upgrade von einer früheren Haupt- oder Nebenversion betreffen könnten. Diese Notizen beschreiben normalerweise Änderungen an Standardvariablenwerten oder Variablen, die entfernt wurden.

  • deprecations: Wenn eine Variable veraltet ist (idealerweise mit dem Deprecation-Filter), sollte sie durch Anmerkungen in diesem Abschnitt kommuniziert werden. Beachten Sie, dass, wenn eine Variable vollständig entfernt wurde, sie nicht veraltet ist und das Entfernen im Abschnitt Upgrade vermerkt sein sollte.

Einreichen einer Spezifikation

Indem Sie einen Entwurf für eine Spezifikation vorschlagen, können Sie der OpenStack-Ansible-Community helfen, den Überblick darüber zu behalten, welche Rollen oder großen Änderungen entwickelt werden. Vielleicht können Sie sich mit anderen Interessenten in Verbindung setzen, die Ihnen dabei helfen können.

Unser Spezifikations-Repository folgt den üblichen OpenStack- und OpenStack-Ansible-Richtlinien für die Übermittlung von Code.

Um Ihnen beim Schreiben der Spezifikation zu helfen, haben wir jedoch eine Spezifikationsvorlage, die in den neuesten Versionsnamenordner kopiert werden kann. Benennen Sie es um und bearbeiten Sie es für Ihre Bedürfnisse.

Ansible-Stil Anleitung

YAML-Formatierung

Wenn Sie Aufgaben und andere Rollen für die Verwendung in Ansible erstellen, erstellen Sie diese bitte im YAML-Wörterbuchformat.

Beispiel für ein YAML-Wörterbuchformat:

- name: The name of the tasks
   module_name:
     thing1: "some-stuff"
     thing2: "some-other-stuff"
   tags:
     - some-tag
     - some-other-tag

Beispiel was NICHT zu tun ist:

- name: The name of the tasks
  module_name: thing1="some-stuff" thing2="some-other-stuff"
  tags: some-tag
- name: The name of the tasks
  module_name: >
    thing1="some-stuff"
    thing2="some-other-stuff"
  tags: some-tag

Verwendung der „>“ und „|“ Operatoren sollten auf Ansible-Bedingungen und Befehlsmodule wie Ansible shell oder command beschränkt sein.

Tags und Tags Konventionen

Tags werden basierend auf der Relevanz jedes einzelnen Elements zugewiesen. Höhere Level beinhalten (z.B. in den tasks/main.yml) High-Level-Tags. Zum Beispiel *-config oder *-install. Enthaltene Aufgaben können detailliertere Tags enthalten.

Die folgende Konvention wird verwendet:

  • Ein Tag, der das Wort install enthält, behandelt Softwareinstallationsaufgaben. Ein Playbook mit -Tags laufen lassen <role>-install stellt nur die erforderliche Software auf dem Ziel bereit und konfiguriert es nicht für Ihre Bedürfnisse oder führt keinen Dienst aus.

  • Ein Tag mit dem Wort config bereitet die Konfiguration der Software vor (angepasst an Ihre Bedürfnisse) und alle Komponenten, die notwendig sind, um die in der Rolle konfigurierten Dienste auszuführen. Ein Playbook mit -Tags <role> -config laufen lassen ist nur möglich, wenn das Ziel bereits die Tags <role> -install ausgeführt hat.

  • Ein Tag mit dem Wort upgrade behandelt alle Upgrade-Aufgaben.

Konventionen für variable Dateien

Die Variablendateien in einer Rolle sind in drei Bereiche unterteilt:

  1. Die Datei defaults/main.yml

  2. Die vars/main.yml-Datei

  3. Die vars/<platform specific> .yml Datei

Die Variablen mit niedrigerer Priorität sollten in defaults/main.yml stehen. Dies ermöglicht ihr Überschreiben mit Gruppenvariablen oder Hostvariablen. Ein gutes Beispiel hierfür sind Standard-Datenbankverbindungsdetails, Verbindungsdetails für Standardwarteschlangen oder Debug-Modus.

Mit anderen Worten, defaults/main.yml enthält Variablen, die von einem Deployer oder einem Continuous Integration System überschrieben werden können. Diese Variablen sollten so weit wie möglich begrenzt werden, um eine Erhöhung der Testmatrix zu vermeiden.

Die vars/main.yml ist immer enthalten. Sie enthält generische Variablen, die von einem Deployer nicht geändert werden sollen. Dazu gehören beispielsweise statische Informationen, die nicht verteilungsspezifisch sind (wie zum Beispiel die Aggregation von internen Rollenvariablen).

Die vars/<platform specific>.yml ist der Ort, an dem der vertriebsspezifische Inhalt gespeichert wird. Diese Datei enthält beispielsweise die Paketnamen, URLs der Repositorys und Schlüssel, Dateipfade, Dienstnamen/Init-Skripts.

Geheimnisse

Alle geheimen Schlüssel (z.B. Kennwörter) sollten nicht mit Standardwerten in den Aufgaben-, Rollen- oder Rollenstandards versehen werden. Die Aufgaben sollten so implementiert werden, dass alle erforderlichen, jedoch nicht bereitgestellten Geheimnisse dazu führen, dass die Aufgabenausführung fehlschlägt. Es ist wichtig, dass bei einer standardsicheren Implementierung sichergestellt wird, dass eine Umgebung aufgrund der Produktionsverwendung von Standardgeheimnissen nicht anfällig ist. Deployer müssen gezwungen werden, ihre eigenen geheimen Variablenwerte ordnungsgemäß anzugeben.

Task-Dateien Konventionen

Die meisten OpenStack-Dienste folgen einer Reihe von Schritten, um eine Servicebereitstellung zu installieren, zu konfigurieren oder zu aktualisieren. Dies wird offensichtlich, wenn Sie tasks/main.yml für vorhandene Rollen überprüfen.

Wenn Sie eine neue Rolle entwickeln, beachten Sie bitte die Konventionen der bestehenden Rollen.

Test Konventionen

Die Konventionen für das Schreiben von Tests sind auf der Seite Testen beschrieben.

Andere OpenStack-Ansible-Konventionen

Um die Entwicklung und die Tests aller OpenStack-Ansible-Rollen zu erleichtern, muss ein Basissatz von Ordnern und Dateien implementiert werden. Ein Basissatz von Skripts zur Konfiguration und zur Testunterstützung muss mindestens Folgendes enthalten:

  • tox.ini: In dieser Datei sind der Lint-Test, der Dokumentations-Build, der Release-Note-Build und der funktionale Build-Ausführungsprozess für die Gate-Tests der Rolle definiert.

  • test-requirements.txt: Die Python-Anforderungen, die beim Ausführen der Tests installiert werden müssen.

  • bindep.txt: Die binären Anforderungen, die auf dem Host installiert werden müssen, auf dem die Tests ausgeführt werden, damit die Python-Anforderungen und die Tox-Ausführung funktionieren. Dies muss aus dem openstack-ansible-tests-Repository kopiert werden und wird automatisch von unserem Vorschlags-Bot überschrieben, sollte eine Änderung eintreten.

  • setup.cfg und setup.py: Informationen zum verwendeten Repository beim Erstellen von Artefakten.

  • run_tests.sh: Ein Skript, mit dem Entwickler alle Standardtests auf einem geeigneten Host ausführen können. Dies muss aus dem openstack-ansible-tests-Repository kopiert werden und wird automatisch von unserem Vorschlags-Bot überschrieben, sollte eine Änderung eintreten.

  • Vagrantfile: Eine Konfigurationsdatei, die es einem Entwickler ermöglicht, einfach eine virtuelle Testmaschine mit Vagrant zu erstellen. Dies muss automatisch run_tests.sh ausführen. Dies muss aus dem openstack-ansible-tests-Repository kopiert werden und wird automatisch von unserem Vorschlags-Bot überschrieben, sollte eine Änderung eintreten.

  • README.rst, LICENSE, CONTRIBUTING.rst: Ein Satz von Standard-Dateien, deren Inhalt selbsterklärend ist.

  • .gitignore: Eine Standard-Git-Konfigurationsdatei für das Repository, die in allen Repositories ziemlich einheitlich sein sollte. Dies muss aus dem openstack-ansible-tests-Repository kopiert werden und wird automatisch von unserem Vorschlags-Bot überschrieben, sollte eine Änderung eintreten.

  • .gitreview: Eine Standarddatei, die für das Projekt konfiguriert wurde, um das Plugin git-review zu informieren, wo sich der Upstream-Gerrit-Remote für das Repository befindet.

  • docs/ und release_notes/ Ordner müssen existieren und korrekt konfiguriert sein.

Bitte sehen Sie sich eine Rolle wie os_cinder, os_keystone oder os_neutron für die neuesten Dateien an.

Container Technologie Unabhängigkeit

Die Rollenimplementierung sollte so durchgeführt werden, dass sie unabhängig davon ist, ob sie in einem Container oder auf einem physischen Host implementiert ist. Die Testinfrastruktur kann Container für die Trennung von Diensten verwenden, aber wenn eine Rolle von einem Playbook verwendet wird, das auf einen Host abzielt, muss es unabhängig davon funktionieren, ob dieser Host ein Container, ein virtueller Server oder ein physischer Server ist. Die Verwendung von Containern für Rollentests ist nicht erforderlich, kann jedoch nützlich sein, um ein Multi-Node-Build als Teil der Testinfrastruktur zu simulieren.

Minimal unterstützte Distributionen

Siehe unsere Seite Unterstützte Distributionen.