Beitragshandbuch

OSIRIS JSON wird öffentlich entwickelt und begrüßt Beiträge jeder Größe: Fragen, Klarstellungen, Beispiele, Reviews und Verbesserungen des Toolings. Als Open-Source-Projekt möchten wir unseren Beitragenden etwas zurückgeben und helfen gern mit Orientierung zu PRs, technischer Redaktion und dabei, jede Feature-Idee in die Realität umzusetzen.

[!Tip]

Für neue Beitragende: Werfen Sie einen Blick auf https://github.com/firstcontributions/first-contributions für hilfreiche Informationen zum Beitragen

[!Info] MVP-Phase (einzelner Maintainer) OSIRIS JSON wird derzeit von einem einzelnen Lead-Maintainer betreut. Reviews und Antworten erfolgen nach bestem Aufwand und können je nach Arbeitslast Zeit benötigen. Der Fokus liegt darauf, die Spezifikation kohärent, vendor-neutral und stabil zu halten, während das anfängliche Ökosystem aufgebaut wird.

Wo Sie sich beteiligen können

Wozu Sie beitragen können

Dokumentation (empfohlener Einstiegspunkt)

Verbesserungen an der Dokumentation sind immer wertvoll und in der Regel am schnellsten zu überprüfen:

• Tippfehler und defekte Links beheben
• Formulierungen dort präzisieren, wo die spec mehrdeutig ist
• Erklärungen und Navigation zwischen Seiten verbessern
• Hinweise zu „how to validate“ oder „how to read an OSIRIS JSON document“ erweitern

Beispiele

Sie können beitragen, indem Sie:

• neue Beispielszenarien vorschlagen
• Lesbarkeit und Konsistenz bestehender Beispiele verbessern
• Kommentare oder begleitende Hinweise hinzufügen, die Leserinnen und Lesern helfen zu verstehen, warum bestimmte Felder vorhanden sind

Spezifikation und schema

Für Beiträge zu spec/schema:

• eine issue eröffnen, die die Änderung und Motivation beschreibt
• ein minimales Beispiel einfügen, das das Problem zeigt
• die kleinste mögliche Änderung vorschlagen, die die Kompatibilität erhält

Wie Beiträge leicht zu reviewen bleiben

• Bevorzugen Sie kleine, fokussierte PRs.
• Vermeiden Sie das Vermischen nicht zusammenhängender Änderungen (z. B. Refactor + neues Feature im selben PR).
• Halten Sie die Sprache präzise (normative Aussagen sollten MUST/SHOULD/MAY nur dort verwenden, wo es angemessen ist).
• Wenn eine Änderung die Kompatibilität beeinflussen könnte, nennen Sie das ausdrücklich in der PR-Beschreibung.

Beitragende

Dieses Projekt wird derzeit von einem einzelnen Lead-Maintainer betreut. Beitragende werden hier und im Laufe der Zeit auf der Maintainer-Seite aufgeführt.

Code of Conduct

Die Teilnahme an der OSIRIS-JSON-Community wird durch den Code of Conduct geregelt.
Lesen Sie den Code of Conduct

KI-unterstützte Beiträge (erlaubt, aber verantwortungsvoll)

KI als Hilfsmittel zu nutzen ist in Ordnung. Nicht in Ordnung ist es, issues/PRs massenhaft zu erstellen, ohne das Projekt zu verstehen.

Wenn Sie KI verwenden:

• Sie sind für Korrektheit und Umfang verantwortlich
• Lesen und verstehen Sie den Code/die spec, die Sie ändern
• Validieren Sie Ausgaben (tests, linters, schema validation, Beispiele)
• Öffnen Sie keine „spekulativen“ issues, die Sie nicht reproduziert haben
• Vermeiden Sie beiläufige Refactors, die große Bereiche ohne Zweck umbenennen/neu formatieren

Maintainer können ohne ausführliche Diskussion schließen:

• Doppelte issues
• Issues ohne reproduzierbare Schritte/ohne Kontext
• PRs, die klar wenig Aufwand erkennen lassen, automatisch generiert sind oder nicht zur Projektrichtung passen

Erste Schritte

1. Forken Sie das Repo und klonen Sie Ihren Fork
2. Erstellen Sie in Ihrem Fork einen Branch:
   • feat/<short-topic> or fix/<short-topic>
3. Nehmen Sie Ihre Änderungen in kleinen Commits vor
4. Öffnen Sie früh einen Draft PR, wenn Sie Feedback möchten
5. Markieren Sie als bereit, wenn:
   • Tests pass
   • Docs/examples updated
   • die PR-Beschreibung vollständig ist

Pull-Request-Checkliste

Bitte nehmen Sie in Ihre PR-Beschreibung auf:

• What ändert dieser PR?
• Why ist er notwendig? (Link zu issue/discussion)
• How haben Sie ihn getestet?
• Gibt es breaking changes?

Checklist

• Ich habe die relevante issue/discussion verlinkt (oder erklärt, warum keine existiert)
• Ich habe den Umfang fokussiert gehalten und nicht zusammenhängende Änderungen vermieden
• Ich habe tests hinzugefügt/aktualisiert (falls zutreffend)
• Ich habe docs/examples aktualisiert (falls zutreffend)
• Ich habe formatting/linking/tools ausgeführt, die in diesem Repo verwendet werden (falls zutreffend)

Commit-Messages (empfohlen)

Verwenden Sie klare Nachrichten, optional Conventional Commits:

• feat: ...
• fix: ...
• docs: ...
• chore: ...

Lizenzierung

Mit Ihrem Beitrag stimmen Sie zu, dass Ihre Beiträge unter der Projektlizenz lizenziert werden.

GSoC (oder ähnliche Programme)

Wenn Sie mit Blick auf eine Bewerbung beitragen:

• Konzentrieren Sie sich auf einen sinnvollen Bereich
• Zeigen Sie, dass Sie klar kommunizieren, kleine Verbesserungen liefern und auf Feedback iterieren können
• Ein kurzes Design-Dokument oder eine Vorschlagsdiskussion ist wertvoller als viele PRs mit geringer Wirkung