Spigot-Plugin-Vorlage

Spigot-Plugin-Vorlage

Sie können diese Vorlage verwenden, um ganz einfach Ihre eigenen hochwertigen Spigot-Plugins mit Gradle zu entwickeln.

Sehen Sie sich die Minecraft-Server-Vorlage an, um Ihr Minecraft-Netzwerk in weniger als 30 Sekunden schnell zu starten.

• Merkmale
• Schnellstart-Setup
• Veröffentlichung einer neuen Version Ihres Plugins
  • Commit-Nachrichtenformat
• Veröffentlichen Sie Ihr Maven-Paket
  • Über die Gruppe und die Artefakt-ID
  • Github-Paketauthentifizierung
• Debuggen Sie Ihr Plugin
  • Kopieren Sie Ihr Plugin automatisch
  • Ausführen und Debuggen des Minecraft-Servers
• Referenzen

Merkmale

Die Vorlage oder besser Boilerplate enthält viele Funktionen, die nützlich sind, wenn Sie hochwertige Plugins entwickeln möchten. Sie müssen jedoch nicht alle davon nutzen, sondern können einfach die Funktionen entfernen, die Sie nicht benötigen.

• Gebrauchsfertiges Gradle -Projekt mit vielen Hilfsaufgaben
• Automatische Generierung von plugin.yaml basierend auf Projekteigenschaften mit SpiGradle
• Integrierter Spigot-Testserver mit einem Klick zum Erstellen, Kopieren des Plugins und Starten des Debuggens in der IntelliJ-Aufgabe
• Gradle Shadow-Plugin zum einfachen Versenden Ihrer benötigten Abhängigkeiten mit Ihrem Plugin
• Beispielintegrationen einschließlich Tests für das Annotation Command Framework und Vault.
• JUnit 5- Testaufbau inklusive MockBukkit und AssertJ
• Bericht zur Jacoco-Codeabdeckung, einschließlich einer Aufgabe zum Hochladen auf Codecov
• Vollständig integrierte Semantic-Release- Release-Pipeline
• Automatische Änderungsprotokollgenerierung basierend auf herkömmlichen Commit-Nachrichten
• Github Actions -Workflow für Build und Release
• Veröffentlichung von Maven-Artefakten in GitHub-Paketen

  Es ist kein selbstgehosteter Nexus oder Artefaktserver mehr erforderlich

• GitHub- Problemvorlagen für Fehler- und Funktionsanfragen
• Richtlinien für Beiträge und Verhaltenskodex
• Schöne Abzeichen zur Präsentation Ihres Projekts

Schnellstart-Setup

• Erstellen Sie mit dieser Vorlage ein neues Github-Projekt.
• Klonen Sie das neue Repository und öffnen Sie es in IntelliJ.
• Aktualisieren Sie die Datei gradle.properties und ändern Sie die folgenden Variablen:
  • group : Ihre-Maven-Gruppen-ID (z. B. io.github.silthus)
  • pluginName : IhrPluginName
  • author : YourName
• Aktualisieren Sie den root.projectName in Settings.gradle . Dies wird Ihre artifactId sein.
• Löschen Sie CHANGELOG.md . Es wird bei Ihrer ersten Veröffentlichung generiert.
• Aktualisieren Sie die README so, dass sie auf Ihr Projekt und die Spigot-Ressourcen-ID verweist.
• Benennen Sie das Java-Paket und das Plugin entsprechend Ihrem Projekt um.
• Führen Sie dann die Gradle-Aufgabe prepareSpigotPlugins aus. Dadurch wird versucht, alle Plugin-Abhängigkeiten herunterzuladen und sie in debug/spigot/plugins/ abzulegen.
• Starten Sie den Minecraft-Server, indem Sie die Aufgabe debugPaper ausführen. Dadurch wird der Server im Hintergrund gestartet und Sie können über die Adresse localhost:25565 eine Verbindung zu ihm herstellen.
• Code weg :) – und sobald Sie bereit sind, übertragen Sie Ihren Commit (im herkömmlichen Commit-Stil) auf „Master“.

Bitte lesen Sie die Beitragsrichtlinien, bevor Sie Pull-Anfragen einreichen oder Probleme eröffnen.

NOTIZ
Möglicherweise müssen Sie nach dem Umbenennen der Pakete die Aufgabe gradle clean ausführen und das Gradle-Projekt erneut importieren, um Fehler beim Generieren von plugin.yml zu beheben.

Veröffentlichung einer neuen Version Ihres Plugins

Einer der Hauptvorteile dieser Vorlage ist die Tatsache, dass sie bei jedem Push-to master automatisch eine neue Version basierend auf Ihren Commit-Nachrichten veröffentlicht . Dadurch wird sichergestellt, dass Ihr Plugin gemäß den Richtlinien zur semantischen Versionierung veröffentlicht wird. Damit dies funktioniert, müssen Sie einige einfache Regeln befolgen:

• Übertragen Sie nur funktionierenden und getesteten Code in den Master-Zweig. Verwenden Sie Pull Requests, um an größeren Funktionen oder Fehlerbehebungen zu arbeiten und diese zusammenzuführen, wenn Sie dazu bereit sind.
• Jedem Bugfix, jeder Funktion und jeder Änderung sollte ein Commit zugeordnet sein. Mischen Sie nicht mehrere Fehler, Funktionen usw. in einer großen Commit-Nachricht. Halten Sie die Commit-Größe klein und committen Sie häufig.
• Ihre Commit-Nachrichten müssen den herkömmlichen Commit-Regeln folgen.

Commit-Nachrichtenformat

Weitere Details und Beispiele zu diesem Thema finden Sie auf der herkömmlichen Commit-Homepage. Aber hier ist eine kurze Zusammenfassung, um Ihnen den Einstieg zu erleichtern.

Die Spezifikation „Conventional Commits“ ist eine einfache Konvention zusätzlich zu Commit-Nachrichten. Es bietet einen einfachen Satz von Regeln zum Erstellen eines expliziten Commit-Verlaufs. Dadurch ist es einfacher, darüber automatisierte Tools zu schreiben. Diese Konvention passt zu SemVer, indem sie die Funktionen, Korrekturen und Breaking Changes beschreibt, die in Commit-Nachrichten vorgenommen werden.

Die Commit-Nachricht sollte wie folgt aufgebaut sein:

 [optional scope]: 

[optional body]

[optional footer(s)]

Der Commit enthält die folgenden Strukturelemente, um den Verbrauchern Ihrer Bibliothek oder Ihres Plugins die Absicht mitzuteilen:

• fix: Ein Commit vom Typ „fix“ behebt einen Fehler in Ihrer Codebasis (dies korreliert mit PATCH in der semantischen Versionierung).
• feat: Ein Commit vom Typ feat führt eine neue Funktion in die Codebasis ein (dies korreliert mit MINOR in der semantischen Versionierung).
• BREAKING CHANGE: ein Commit, der eine BREAKING CHANGE:-Fußzeile hat oder ein ! anhängt führt nach dem Typ/Bereich eine bahnbrechende API-Änderung ein (korreliert mit MAJOR in der semantischen Versionierung). Eine BREAKING CHANGE kann Teil von Commits jeglicher Art sein.
• Andere Typen als fix: und feat: sind zulässig, zum Beispiel empfiehlt @commitlint/config-conventional (basierend auf der Angular-Konvention) build: , chore: , ci: , docs: , style: , refactor: , perf: , test: , und andere.
• Andere Fußzeilen als BREAKING CHANGE: können bereitgestellt werden und einer Konvention folgen, die dem Git-Trailer-Format ähnelt. Zusätzliche Typen werden von der Spezifikation für konventionelle Commits nicht vorgeschrieben und haben keine implizite Auswirkung auf die semantische Versionierung (es sei denn, sie enthalten eine BREAKING CHANGE).

Für den Typ eines Commits kann ein Bereich bereitgestellt werden, um zusätzliche Kontextinformationen bereitzustellen. Er ist in Klammern enthalten, z. B. feat(parser): add ability to parse arrays .

Hier einige Beispiele:

Commit-Nachricht mit Beschreibung und Breaking-Change-Fußzeile

 feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

Commit-Nachricht ohne Text

 docs: correct spelling of CHANGELOG

Commit-Nachricht mit Gültigkeitsbereich

 feat(lang): add polish language

Commit-Nachricht mit Textkörper aus mehreren Absätzen und mehreren Fußzeilen

 fix: correct minor typos in code

see the issue for details

on typos fixed.

Reviewed-by: Z
Refs #133

Veröffentlichen Sie Ihr Maven-Paket

Ihr Plugin wird automatisch als Maven-Paket auf Github-Paketen veröffentlicht, sobald Sie eine neue Version veröffentlichen.

Über die Gruppe und die Artefakt-ID

Die durch Ihre artifactId angehängte group wird verwendet, um Ihr Projekt beim Importieren in andere Projekte eindeutig zu identifizieren. Wenn Sie Spigot in Ihr Projekt importieren, verwenden Sie die Gruppe org.spigotmc gefolgt von der Artefakt-ID spigot-api und der Version.

Das Folgende wurde dem offiziellen Leitfaden zur Benennung von Maven entnommen.

• groupId identifiziert Ihr Projekt eindeutig über alle Projekte hinweg. Eine Gruppen-ID sollte den Paketnamensregeln von Java entsprechen. Das bedeutet, dass es mit einem umgekehrten Domänennamen beginnt, den Sie kontrollieren. Zum Beispiel: org.apache.maven , org.apache.commons .
  Wenn Sie keine Domain besitzen, können Sie die Github-Domain io.github verwenden, an die Ihr Github-Benutzername angehängt ist, z. B. io.github.silthus
• artifactId ist der Name der JAR-Datei ohne Version. Wenn Sie es erstellt haben, können Sie einen beliebigen Namen mit Kleinbuchstaben und ohne seltsame Symbole wählen. Zum Beispiel: „maven, commons-math.“

Github-Paketauthentifizierung

Sie müssen die Authentifizierung für Github-Pakete konfigurieren, wenn Sie Ihr Maven-Paket in anderen Projekten verwenden möchten.

1. Erstellen Sie ein persönliches Github-Zugriffstoken
2. Erstellen oder aktualisieren Sie die gradle.properties in C:Users%username%.gradle wie folgt und ersetzen Sie YOUR_GITHUB_USERNAME durch Ihren Github-Benutzernamen und YOUR_PERSONAL_ACCESS_TOKEN durch das Zugriffstoken aus Schritt 1.

 gpr.user =YOUR_GITHUB_USERNAME
gpr.key =YOUR_PERSONAL_ACCESS_TOKEN

Debuggen Sie Ihr Plugin

Kopieren Sie Ihr Plugin automatisch

Sie können Ihr Plugin mit der Gradle-Aufgabe „ prepareSpigotPlugins “ aus Ihrem Arbeitsverzeichnis in das Plugins-Verzeichnis exportieren. Die Aufgabe erstellt und kopiert Ihr Plugin automatisch in das plugins/ -Verzeichnis.

Ausführen und Debuggen des Minecraft-Servers

Sie können Ihr Plugin mithilfe der Server Ausführungskonfiguration in IntelliJ ausführen oder debuggen, um den Minecraft-Server automatisch herunterzuladen, ihn zu erstellen, Ihre und abhängigen Plugins hinein zu kopieren und ihn im Debugging-Modus zu starten.

Dies liegt an der unglaublichen Leistungsfähigkeit der Debug-Aufgaben von Spigradle. Erfahren Sie mehr auf der Spigradle-Github-Seite.

Referenzen

• Spigradle: Bietet tolle Gradle-Aufgaben, die Ihr Leben viel einfacher machen
• semantic-release: Meiner Meinung nach sollte jedes Projekt dies verwenden!
• Herkömmliche Commit-Nachrichten: Commit-Nachrichten richtig ausführen