Contributing to Spigot

Sep 29, 2021
Contributing to Spigot
  • First Step: IDE

    The first step for developing anything, whether its contributing to Spigot or making your own program is to find out which environment you want to develop in. Seeing as this is a guide for developing with IntelliJ IDEA, we will go ahead and use that IDE. You can download that IDE from here.

    You can install it using the default settings it provides for you. Feel free to change the look and feel to suit your needs, or install some plugins if you wish.

    Stash Access + Contributing
    The first step to getting stash access is to read the Contributing to the Project post here. Make sure you read the part about the CLA, as that is pretty important, and the next step to getting Stash access.

    Wait patiently, but if it takes longer than 24 hours, you can jump on IRC or Discord and let a staff member know.

    Forking desired Repository
    Once you have access to the stash, you can Fork a repository rather than just clone one. A fork actually creates a repository on your Stash Profile page.

    Simply Navigate to the main repo and choose your desired fork:

    In this case, I am choosing to fork the Bukkit repository. The fork option can be found under the ellipses [...] on the left hand menu bar, under the spigot logo.

    Click Fork Repository


    You will then be able to view your new repo on your profile page!


    You are now able to clone your fork of the main repository using its URL (example: Cloning downloads the project to your local drive where you can then make changes to it, commit these changes, and then push them back to your fork on the Stash server.


    Importing a Project using Maven's pom.xml

    Spigot uses a dependency manager called Maven. This is a huge time saver, in all aspects of development. Instead of having to manually hunt down the libraries we use to build and compile Spigot-Server, Bukkit, CraftBukkit and whatever other java programs you want to use, Maven allows us to do that automatically.

    When you open up IntelliJ, you have the selection to open a new project, or import a new project. For a maven installation, select Import project.


    Now you can simply select the pom.xml for the project you want to work on as shown in the image below. This will download all the dependencies you need, and will allow you to promptly work on developing your own custom Spigot.jar, CraftBukkit.jar, Bukkit.jar files.

    Note: You likely want to import the project via the pom of your cloned fork. A common mistake is to open and apply changes in the projects generated by BuildTools: Be aware that the files of these projects are replaced with those of the master branches of the Spigot main repositories whenever you run the BuildTools again. Any of your uncommitted changes in these projects will then be lost.
    You currently cannot use the BuildTools to build the server with your custom changes. You have to build the server jars via Maven.


    -------------Use Maven Instructions below-----------
    In Order to test your build, you need to create an artifact.
    • Click on the Green + button in the top left hand corner of the new window.
    • JAR -> From modules with dependencies
    • For the Main Class Click the browse (...) and select Main in the pop up window. (It will appear after loading)
    • Extract to the target JAR
    • and hit Okay.
    You should now be able to Build -> Spigot. This will be the Spigot.jar you can test with.

    Building a JAR has just gotten easier! Instead of adding an Artifact, simply:

    • Navigate to the right-hand side of the IntelliJ window, and select Maven Projects.

    • If you Expand the Spigot folder, you will see LifeCycle, Plugins and Dependencies.

    • Open LifeCycle and find 'Package'. Double clicking this will run the packing tool and spit out a JAR file in /Spigot/Spigot-Server/target/spigot-1.9-R0.1-SNAPSHOT.jar
    You can use this JAR file to test your changes.

    Note: You can also use the other packages to run tests, compile, etc for this project.
    Testing Your new Spigot.jar
    To run a Minecraft Spigot Server Locally, Select Run->Edit Configurations...
    Select the Green Plus, and type JAR, and select JAR Application
    The Path to JAR will be the path to the newly made Spigot.jar that you just built. Probably look something like: Spigot-Server\out\artifacts\spigot_jar

    Make your Working Directory a new Folder within the current project (or anywhere, this is going to contain all the Spigot Server Files though, which means lots will be made).

    You can add in the Before Launch: Build Artifacts, Activate tool window the option to Build 'spigot.jar' artifact


    For Debugging, you can add a Remote. The options will remain unchanged unless you want to change the name.

    If you now press Run -> Spigot, and you get
    Code (Text):
     no manifest attribute
    You need to move the META-INF folder from src/main/java/META-INF to src/main/resources


    Creating a Patch V.0.1

    Write your code, make your changes. For command line GIT (this is what I use, not really sure about tortoise-git etc.,) navigate to your repo that you changed. If you were working in Spigot-Server go there.

    Code (Text):

    git add src/
    git commit
    //enter commit message here
    Then change directories to the main directory

    Code (Text):

    cd ../../
    ls  Bukkit  Bukkit-Patches  CraftBukkit  CraftBukkit-Patches  pom.xml  Spigot-API  Spigot-Server
    and run the

    Code (Text):

    The patch should run and it will pop it into CraftBukkit-Patches

    Code (Text):

    ls CraftBukkit-Patches | grep 0151-Adds-fix-for-sheep-shearing.patch
    You can now submit a pull request following the next step.

    I am almost positive this is the way it's supposed to work, but I could be wrong. This guide so far does not show much for testing, or to see if your patch will be cleared. Will be updating that soon.

    Will update with Pictures.

    The next step is to create a fork of the repo. Normally, the first step would be to clone the repo, but as we have generated our stuff from BuildTools.jar we already have a clone. So we need to add a upstream remote.
    Code (Text):

    git remote add upstream  //output from git remote -v
    Then we can pull the changes to keep our branch updated.
    Code (Text):

    git fetch upstream
    git merge upstream/master
    //which is the same as:
    git pull upstream master
    Now that you have your local master branch updated with changes from the original repo, we can start working our own commits!

    Checkout a branch that defines what you are working on.
    Code (Text):

    git checkout -b sheep_shear_fix_03082016
    Make your commits with good messages
    Code (Text):

    git commit -m "Fixes shearing bug with sheep"
    then push using
    Code (Text):

    git push -u origin sheep_shear_fix_03082016
    And submit a pull request

    Log into the stash, find the repo you are working on, and you can click the ellipses {...} to create a pull request.

    Notes: Will update w/Pictures

    The API side of Spigot
    Unlike CraftBukkit and Spigot, Bukkit is easier to contribute to, because it does not require generating patches for Minecraft server files.

    To Contribute to Bukkit:

    • Follow above to Fork the Bukkit Repository to your Stash Profile.
    • Clone Your Bukkit Repository to your Local Machine.
    • Open the pom.xml file of the newly cloned repo.
    • Checkout a new branch with a descriptive name
      • git checkout -b tm_world_sleep_event
    • Apply your changes to the code.
      • git add src/
      • git commit -m "Adds WorldSleepEvent"
      • git push origin tm_world_sleep_event
    • Go back to the main stash of Spigot.
    • Navigate to Bukkit Stash
    • Click Pull Request (or Create Pull Request)
    • On the top (wanting to merge in) select your Forked Repository
    • On the right top, select your BRANCH (note: not master.)
    • On the bottom Left select the spigot repo.
    • Same for bottom right.
    • On the next page add a description, and a link to the issue on the JIRA, and any other descriptions you may want to include.
    • Leave the reviewers blank.
    • Submit your PR!
    The Implementation side of Spigot​

    CraftBukkit runs off a patch system and that is how we manage our version control.

    Follow the above guide to fork and clone a repository for CraftBukkit. Open that project using the pom.xml as well. The steps for Generating a patch and comitting/creating a Pull Request are as follows:

    • Fork Craft Bukkit
    • Clone your new repo
    • Download BuildTools.jar and move to a separate folder (it will generate a lot of files next step)
    • Run BuildTools.jar (follow the guide at the bottom of this post)
    • Now we need to generate some code from the current existing patches in order to have all the classes and files necessary to compile and build the project.
      • make sure you are in the directory of your cloned CraftBukkit repo.
      • run:
        • ./applyPatches /path/to/buildtools/work/decompile-xxxx
      • That will generate the appropriate nms-files and classes. Make sure that you don't add these to version control. The only code that gets added to version control is the nms-patches/ directory.
    • You can now edit the CraftBukkit code and make your changes/implementations.
    • When you are finished, run the following commands to create a patch for the work that you've completed.
      • make sure you are in the directory of your cloned CraftBukkit repo.
      • run:
        • ./makePatches /path/to/buildtools/work/decompile-xxxx
        • git add nms-patches
        • git commit -m "Adds implementation of x"
        • git push origin your_branch_name
    • Now that your branch is all updated, you can follow the creating a PR guide above under Bukkit.
    Side Guide:
    Using BuildTools!

    You can download Buildtools.jar from here.

    Move the file from the original location (unless that's where you want to generate the many files that will be generated) to it's own location. Open your command line tool (Git Bash or Cygwin for windows, or just terminal for Unix. There's also a Windows GUI available.) and run the following command. You must have java installed to run.


    After running for probably a minute, you will now see a bunch of files generated.
  • Loading...
  • Loading...