Zum Inhalt

Aufnahme in das Softwareverzeichnis

Im openCode-Softwareverzeichnis werden Projekte öffentlich sichtbar, durchsuchbar und auffindbar gemacht. Möchten Sie Ihr Softwareprojekt ebenfalls im Softwareverzeichnis führen lassen, müssen folgende Vorraussetzungen erfüllt sein:

  • Ihr Projekt liegt auf gitlab.opencode.de
  • Das Projekt ist öffentlich zugänglich
  • Es enthält eine Datei publiccode.yml im Hauptverzeichnis

Was ist die publiccode.yml?

Die publiccode.yml ist eine Standard für Metadaten, mit der Sie Open-Source-Projekte für den öffentlichen Sektor beschreiben. Die Datei muss sich dabei im obersten Ordner Ihres Repositories auf https://gitlab.opencode.de/ befinden und genau diesen Dateinamen tragen. Pro Repository bzw. Projekt kann nur eine solche Datei abgelegt werden. Die notwendigen Schlüsselworte und Anforderungen an die publiccode.yml entspringen dem Metadaten Standard für Software von Öffentlichen Verwaltungen.

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.

  4. 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 Kategorien.

    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
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 IETF BCP 47 language tag (siehe https://en.wikipedia.org/wiki/IETF_language_tag)
    - de
    - en

  5. 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.

  6. Tragen Sie die Softwaredetails ein: Geben Sie an, unter welcher Lizenz Ihr Projekt steht und wo der Code liegt. Eine Liste der zugelassenen Lizenzen finden Sie hier. Außerdem benennen Sie hier einen Kontakt, der die Software betreut.

    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"

  7. Prüfen und veröffentlichen: Am Einfachsten überprüfen Sie Ihre publiccode.yml-Datei damit, wenn 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.

Darstellung im openCode Softwareverzeichnis

Diese Abbildung zeigt exemplarisch die Ansicht der aufgefüllten publiccode.yml-Datei auf einer Projektdetailseite im Softwareverzeichnis: "Screenshot dazu, wie man die Grunddaten pflegt"

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 Projekts nicht angezeigt werden, kann das daran 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.
Warum wird mein Projekt nicht in dem openCode Softwareverzeichnis angezeigt?

Dies liegt vermutlich daran, dass Ihre publiccode.yml-Datei fehlerhaft ist oder Einträge in Ihrer publiccode.yml-Datei vergessen wurden. Am Einfachsten überprüfen Sie Ihre publiccode.yml-Datei damit, wenn Sie diese in unseren openCode-Editor laden und danach auf die "Validate"-Schaltfläche klicken.

Wie reiche ich eine Nachnutzung ein?

Zum Einreichen eines Nachnutzungsrechts Ihrer Software müssen Sie folgenden Schritten folgen:

  1. Klicken Sie zuerst auf der Seite Nutzung sichtbar machen auf Nachnutzung einreichen. Sie werden nun auf die Suche von openCode weitergeleitet.
  2. Öffnen Sie hier nun den Eintrag des Projekts, welcher Ihrem Suchbegriff entspricht.
  3. Nach einem Klicken auf Nachnutzung einreichen wird das Formular zur endgültigen Bestätigung der entsprechenden Nachnutzung geöffnet.

Nachdem Sie dieses Formular ausgefüllt und abgeschickt haben, haben Sie die Nachnutzung erfolgreich eingereicht.