General style guide for CivClassics plugin development.
All plugins actively maintained by CivClassic follow these rules in their layout and are formatted according to them. Contributors are expected to follow them as well.
An example repository to illustrate this layout with recommended defaults for most files is provided here
Contains only the following:
The only folder in this directory, which contains all source code and other plugin files. If the plugin contains multiple Maven modules, each module may have it's own top level directory and each contain its own src/ folder.
Specifies basic formatting based on file type and should always be identical to the one here.
Should ignore all common random crap generated by IDEs and Maven, a reference is provided here.
Optional readme describing the general functionality of the plugin.
License the plugin is being developed under. All our plugins use either BSD-3 or MIT.
Maven config file, see (TODO link pom section) for more information.
Follows Maven conventions, as follows:
-
All plugin source code (*.java files) is under src/main/java/full/group/id/artifactid/
-
All non java plugin files (especially plugin.yml and config.yml) are under src/main/resources/
-
All test source code (*.java files) is under src/test/java/full/group/id/artifactid/
-
All non java testing files under src/test/resources/
An example pom.xml is provided here. We'll break down its individual parts in the following:
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://maven.apache.org/POM/4.0.0"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
Generic standard header for any pom.xml
<groupId>com.civclassic.github</groupId>
Group IDs uniquely identify the project across all projects and should follow Java's package name rules and be a reversed ordered version of a domain that you control, eg: org.apache.maven. GroupId should be kept lower case.
<artifactId>template</artifactId>
Artifact IDs represent the name of the plugin and should always be lower case
<version>1.0.2</version>
General plugin versioning separated into MAJOR.MINOR.PATCH. Whenever a change to the plugin is made, it's version should be incremented as follows
- Increments to MAJOR should be kept to refactors and other huge or breaking changes.
- Increments to MINOR should represent API updates and additions such that you might need to update the dependency version for some stuff but only for those that wish to use the new features. Refrain from removing stuff in minor versions, instead deprecate them and provide an alternative. Removals should generally be kept to major versions.
- Increments to PATCH should represent internal changes, bug fixes, javadoc updates, reformats. If something changes the nature of an API or adds a new feature, it should be a minor version instead.
<properties>
<java.compile.version>1.8</java.compile.version>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
</properties>
We currently use Java 8 and recommend using OpenJDK as JDK. Further we use UTF-8 as encoding, because it is what Minecraft uses as well.
<build>
<defaultGoal>clean package source:jar</defaultGoal>
Default goal invoked when running mvn
<resources>
<resource>
<directory>${basedir}</directory>
<includes>
<include>LICENSE.txt</include>
<include>README.md</include>
</includes>
</resource>
<resource>
<directory>src/main/resources/</directory>
<filtering>true</filtering>
</resource>
</resources>
Adds the plugins LICENSE, README and other resources files to the built jar. Also populates build variables in the plugin.yml.
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<configuration>
<source>${java.compile.version}</source>
<target>${java.compile.version}</target>
</configuration>
</plugin>
Ensures java version used is properly set
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.22.2</version>
</plugin>
Executes tests and is only needed if the plugin actually has tests
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<version>3.2.0</version>
<configuration>
<archive>
<addMavenDescriptor>false</addMavenDescriptor>
</archive>
</configuration>
</plugin>
Prevents Maven from putting doxxy system information into the generated jar
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>3.2.3</version>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
<configuration>
<createDependencyReducedPom>false</createDependencyReducedPom>
<transformers>
<transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
<manifestEntries>
<Built-By>Maven</Built-By>
</manifestEntries>
</transformer>
</transformers>
</configuration>
</execution>
</executions>
</plugin>
Keeps Maven from generating a dependency reduced pom (annoying build process file in the top level directory) and also prevents it from putting doxxy system information into the generated jar
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-source-plugin</artifactId>
<version>3.2.0</version>
<executions>
<execution>
<id>attach-sources</id>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
</plugin>
Attaches the plugins source code to the built jar
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.2.0</version>
<executions>
<execution>
<id>attach-javadocs</id>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
</plugin>
Generates Javadocs and attaches them to the built jar
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-checkstyle-plugin</artifactId>
<version>3.1.1</version>
<configuration>
<configLocation>https://raw.githubusercontent.com/CivClassic/style-guide/master/src/main/resources/civclassic_checks.xml</configLocation>
<consoleOutput>true</consoleOutput>
</configuration>
<executions>
<execution>
<id>checkstyle</id>
<goals>
<goal>checkstyle</goal>
</goals>
<phase>prepare-package</phase>
</execution>
</executions>
</plugin>
</plugins>
</build>
Runs checkstyle checks (TODO link to section) based on our configuration and reports eventual violations.
<reporting>
<plugins>
<!-- https://maven.apache.org/jxr/maven-jxr-plugin/ -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jxr-plugin</artifactId>
<version>3.0.0</version>
</plugin>
</plugins>
</reporting>
Produces a cross reference of the projects sources and makes it easier to reference specific lines of code, see also its docu here
<dependencies>
<!-- Hard Dependencies -->
<dependency>
<groupId>org.spigotmc</groupId>
<artifactId>spigot</artifactId>
<version>1.14.4-R0.1-SNAPSHOT</version>
<scope>provided</scope>
</dependency>
<dependency>
...
</dependency>
...
List of dependences, usually the scope of plugins reference should be provided. All dependencies used should be either in Maven Central or one of the additional repositories specified in this pom. A plugin should never require anything other than invoking mvn to build it after cloning it.
<repositories>
<repository>
<id>devoted-repo</id>
<url>https://build.devotedmc.com/plugin/repository/everything/</url>
</repository>
<repository>
<id>spigotmc-repo</id>
<url>https://hub.spigotmc.org/nexus/content/repositories/snapshots/</url>
</repository>
</repositories>
</project>
List of repositories (additionally to Maven Central) used to fetch dependencies. devoted-repo is our official build server and used in almost every plugin, just like the official spigot repo.