Zum Inhalt

Erstellung einer publiccode.yml

Die Datei publiccode.yml ist ein Standardformat für Metadaten, mit dem Open-Source-Projekte im öffentlichen Sektor beschrieben werden können.

Auf openCode werden alle Einträge im Softwareverzeichnis automatisch aus den jeweiligen publiccode.yml-Dateien der Projekte auf der GitLab-Instanz übernommen. Das bedeutet umgekehrt, dass nur Projekte im Verzeichnis erscheinen, die eine gültige publiccode.yml-Datei enthalten.

Diese Anleitung soll Sie nun dabei unterstützen, eine solche publiccode.yml für Ihre Software zu erstellen.

Wie erstelle ich eine funktionierende publiccode-yml-Datei?

  1. Öffnen Sie Ihr Projekt auf GitLab
  2. Navigieren Sie zu Repository > Dateien
  3. Erstellen Sie eine neue Datei mit dem Namen publiccode.yml. Nutzen Sie dafür den openCode-Editor oder laden Sie sich diese kommentierte Vorlage herunter.

Was Sie bei der Erstellung der publiccode.yml berücksichtigen müssen

  1. Pflegen Sie die Grunddaten: Beginnen Sie mit dem offiziellen Schema wie Name, Version Ihrer Software, die URL und passende Kategorien. Auf der Seite des Metadatenstandards finden Sie eine Liste der möglichen Einträge.

    publiccodeYmlVersion: "0.4"    # Version des publiccode.yml-Formats. Bitte nur ändern, wenn Sie wissen, was Sie tun 
name: "PROJEKT_NAME"    # Name der Software
url: "https://gitlab.opencode.de/IHR_PROJEKT"    # URL zu Ihrem Projekt. Die URL ist meist der Direktlink auf Ihr openCode-Repository. Bitte beachten sie, dass nur auf ein Projekt und nicht auf eine Gruppe verlinkt werden darf.
landingURL: "https://IHR-PROJEKT.de"    # URL zu der Webseite Ihrer Software
softwareVersion: "1.0.1"    # Aktuelleste Version Ihrer Software
releaseDate: "2022-01-24"    # Veröffentlichungsdatum
logo: logo.svg     # Pfad zum Logo im obersten Ordner des Projekts. Der Pfad Ihres Logo ist relativ von dem obersten Ordner Ihres Projekts. Erlaubte Dateiformate sind: .svg, .svgz und .png
platforms:    # Unterstützte Plattformen. Bitte wählen Sie aus den folgenden Einträgen: web, windows, mac, linux, ios, android. Eigene Einträge sind nicht möglich
    - linux
    - windows
    - mac
    usedBy:    # Nachnutzung. Es sind beliebig viele Einträge möglich.
    - Zendis
categories:    # Kategorien, die Ihre Software beschreiben. Bitte wählen Sie eine oder mehrere Kategorien aus dem publiccode-Standard: https://yml.publiccode.tools/categories-list.html. Eigene Einträge sind nicht möglich 
    - financial-reporting
    - email-marketing
developmentStatus: development    # Entwicklungsstatus. Wählen Sie eine der folgenden Angaben: concept, development, beta, stable, obsolete
softwareType: "standalone/desktop"    # Software-Typ. Wählen Sie eine der folgenden Angaben: standalone/backend, standalone/desktop, standalone/iot, standalone/mobile, standalone/web, standalone/other, addon, library, configurationFiles
localisation:
    localisationReady: true
    availableLanguages:    # Unterstützte Sprachen. Sprachen im Form eines kleingeschriebenen IETF BCP 47 language tag (siehe https://en.wikipedia.org/wiki/IETF_language_tag). Eigene Einträge sind nicht möglich
        - de
        - en

  2. Füllen Sie die Projektbeschreibung aus: Erklären Sie kurz und klar, was Ihr Softwareprojekt ist und bebildern Sie es mit aussagekräftigen Screenshots. Unsere Empfehlung: Zwei Sprachen pflegen!

    description:
    de:
        genericname: >  # Dieser Schlüssel ist der "genericName", der sich auf die spezifische Kategorie bezieht, zu der die Software gehört. Sie können den generischen Namen normalerweise in einer Präsentation der Software finden, wenn Sie etwas wie folgt schreiben: "Software xxx ist ein yyy" Nennenswerte Beispiele sind zum Beispiel: "Texteditor", "Textverarbeitung", "Webbrowser", "Chat" und so weiter... Der generische Name darf bis zu 35 Zeichen lang sein
        shortDescription: >    # Kurze Beschreibung AUF DEUTSCH. Maximal 150 Zeichen 
        Eine kurze Beschreibungen, welche
        mehrere Zeilen umfassen kann.
        longDescription: >    # Ausführliche Beschreibung AUF DEUTSCH. Dieser Schlüssel enthält eine längere Beschreibung der Software, zwischen 500 und 10000 Zeichen. Sie soll einem potenziellen Benutzer einen Überblick über die Fähigkeiten der Software für einen potenziellen Benutzer geben. Die Zielgruppe für diesen Text sollten die Benutzer der Software sein, nicht die Entwickler. Sie können sich diesen Text vorstellen Text als die Beschreibung der Software, die auf Ihrer Website zu finden wäre (wenn Sie eine hätte). Diese Beschreibung kann einige grundlegende Markdown-Elemente enthalten: *Kursiv*, **fett**, - Aufzählungen und [Links](#)
        Eine sehr lange Beschreibung dieser Software,
        auch auf mehrere Zeilen aufgeteilt.
        Sie sollten beschreiben, worum es bei der Software geht
        und warum man Sie benötigt.
        Hier könnten potenziell viele Seiten Text enthalten sein.
        features:    # Auflistung der Features Ihrer Software (Anführungszeichen beachten!)
        - "Das erste Feature"
        - "Ein anderes zweites Feature"
        screenshots:    # Bildschirmfotos Ihres Projekts. Pfad zu Ihren Screenshots. Die Pfade sind ausgehend von dem obersten Ordner Ihres Projekts
            - .opencode/screenshots/sshot1.jpg
            - .opencode/screenshots/sshot2.jpg
            - .opencode/screenshots/sshot3.jpg
    en:
        genericname: >  # Dieser Schlüssel ist der "genericName", der sich auf die spezifische Kategorie bezieht, zu der die Software gehört. Sie können den generischen Namen normalerweise in einer Präsentation der Software finden, wenn Sie etwas wie folgt schreiben: "Software xxx ist ein yyy" Nennenswerte Beispiele sind zum Beispiel: "Texteditor", "Textverarbeitung", "Webbrowser", "Chat" und so weiter... Der generische Name darf bis zu 35 Zeichen lang sein
        shortDescription: >    # Kurze Beschreibung AUF ENGLISCH. Maximal 150 Zeichen
        A rather short description that
        can span multiple lines.
        longDescription: >    # Ausführliche Beschreibung AUF ENGLISCH. Dieser Schlüssel enthält eine längere Beschreibung der Software, zwischen 500 und 10000 Zeichen. Sie soll einem potenziellen Benutzer einen Überblick über die Fähigkeiten der Software für einen potenziellen Benutzer geben. Die Zielgruppe für diesen Text sollten die Benutzer der Software sein, nicht die Entwickler. Sie können sich diesen Text vorstellen Text als die Beschreibung der Software, die auf Ihrer Website zu finden wäre (wenn Sie eine hätte). Diese Beschreibung kann einige grundlegende Markdown-Elemente enthalten: *Kursiv*, **fett**, - Aufzählungen und [Links](#)
        Very long description of this software, also split
        on multiple rows. You should note what the software
        is and why one should need it. We can potentially
        have many pages of text here.

    Achtung

    Wenn Sie eine Beschreibung in einer Sprache hinzugefügt haben, dann müssen Sie auch die entsprechenden Werte unter dem Eintrag localisation anpassen. Wenn Sie eine Beschreibung in Deutsch und Englisch angegeben haben, dann müsste dieser Eintrag wie folgt aussehen:

    localisation:
    localisationReady: true
    availableLanguages:
        - de
        - en

  3. Bestimme Sie die Zielgruppe (Länder und Themengebiete) der Software:

    intendedAudience:
    countries: # Länder (https://de.wikipedia.org/wiki/ISO-3166-1-Kodierliste), die der Zielgruppe entsprechen. In Kleinbuchstaben!
        - "de"
    scope: # Themenbereiche, die am ehsten denen Ihrer Software entsprechen. Die unterstützten Einträge finden sich unter https://yml.publiccode.tools/scope-list.html#scope-list. Es sind keine eigenen Einträge möglich
        - "local-authorities"
        - "environment"

    Hinweis

    Die Ländercodes unterscheiden sich zum Teil von den Sprachcodes (unter availableLanguages und description). Die möglichen Ländercodes dieses Eintrags finden Sie auf der Wikipedia-Seite zu den ISO-3166-1 Länder-Kodierungen. Die Ländercodes müssen dabei, entgegen der Schreibweise im Wikipedia-Artikel, in Kleinbuchstaben angegeben werden.

  4. Lizenz und Ansprechpersonen hinzufügen: Geben Sie an, unter welcher Lizenz Ihr Projekt steht und wo der Code liegt. Die ausgewählte Lizenz muss auf unserer Liste mit erlaubten Lizenzen stehen. Außerdem benennen Sie hier einen Kontakt, der die Software betreut.

    Hinweis

    Zusätzlich zur Angabe der Lizenz in der publiccode.yml, wird auch eine LICENSE-Datei im Hauptverzeichnis des Projekts benötigt, welche Informationen über die in der Software verwendete Lizenzen enthält. Unsere Badge-API greift dabei auf diese LICENSE-Datei zu - nicht auf die publiccode.yml.

    legal:
license: AGPL-3.0-or-later    # Genutzte Open-Source-Lizenz. Eine Liste der zugelassenen Lizenzen finden Sie im openCode Wissensbereich: https://opencode.de/wissen/rechtssichere-nutzung/open-source-lizenzen#2.-Open-Source-Lizenzliste. Gültig sind Einträge im Format der auf der Seite angegebenen SPDX-Identifier.

maintenance:
type: "community"    # Art der Betreuung. Bitte wählen Sie eine der folgenden Angaben: internal, contract, community, none
contacts:    # Auflistung von Kontakten, welche die Software betreuen
    - name: "Francesco Rossi"
    email: "francesco.rossi@zendis.de"
contractors:    # Vertragspartner:innen
    - name: ZenDis
    email: "hallo@zendis.de"
    website: "zendis.de"
    until: "2023-01-01"

  5. Prüfen und veröffentlichen: Am Einfachsten überprüfen Sie Ihre publiccode.yml-Datei, indem Sie diese in unseren openCode-Editor laden und danach auf die Validate-Schaltfläche klicken. Sollte die Datei fehlerfrei sein, steht der Veröffentlichung nichts mehr im Wege. Nach dem Erstellen der Datei wird Ihr Projekt kurze Zeit später automatisch im Softwareverzeichnis sichtbar.

Anpassen der Darstellung im openCode Softwareverzeichnis

Um die Darstellung Ihrer Software im Softwareverzeichnis am Besten an Ihre Wünsche anzupassen, empfehlen wir Ihnen der weiterführenden Anleitung zur Anpassung der Darstellung im Softwareverzeichnis in diesem Guide zu folgen.

Best-Practices aus der Community

Folgende Beispiele aus der Community können für Sie nützlich sein, um die Erstellung einer publiccode.yml-Datei nachvollziehen zu können:

Häufig gestellte Fragen und Probleme

Wieso werden Logo oder Screenshots meines Projektes nicht angezeigt?

Falls das Logo oder die Screenshots Ihres Projektes nicht angezeigt werden, kann das an folgenden Fehlern liegen:

  • In der publiccode.yml-Datei ist Ihr Logo oder Ihre Screenshots noch nicht aufgeführt. Fügen Sie die Datei hinzu und ergänzen Sie den Pfadnamen. Die Logo-Datei muss sich in dem obersten Ordner Ihres Projekts befinden.
  • Screenshots fügen Sie im Bereich description unter dem Bereich der jeweiligen unterstützen Sprache (z.B. de) ein.
  • Ggf. nutzen Sie ein nicht unterstütztes Dateiformat. Gültige Dateiformate für Logos sind: .svg, .svgz und .png. Gültige Dateiformate für Screenshots sind: .png und .jpg.
  • Der von Ihnen angegebene Pfad zu Ihrer Logo-Datei ist nicht korrekt. Überprüfen Sie den Pfad.
Wie finde ich Fehler in meiner publiccode.yml-Datei?

Am besten nutzen Sie unseren publiccode.yml-Editor, um Ihre publiccode.yml-Datei zu erstellen.

Im Editor können Sie entweder nach dem Hochladen Ihrer publiccode.yml-Datei oder nach dem Ausfüllen der entsprechenden Felder über die Schaltfläche Validate Fehler in Ihrer Datei anzeigen lassen.