Skip to content

Tutorial: Contributing

Jump to bottom
Martijn edited this page Dec 28, 2022 · 25 revisions

This tutorial quickly shows you how to set up a fork of Gale so that you can make a pull request that modifies existing patches or adds new patches.


    ℹ️    This tutorial is written for Gale,    
             but you can follow the same steps on any other fork!    
 

Requirements beforehand

    ✔  You need to know how to open a command terminal and run commands

    ✔  You need to know how to use Git.
           If you don't know Git, check out a tutorial online (for example this one).
           Specifically, you should know how to do an interactive rebase in Git: git rebase -i
           (Check out this video, for example)

    ✔  You will need 6+ GB of free RAM

    ✔  You must have installed Java JDK 17 or higher

    ✔  You must have installed IntelliJ IDEA
           (Other IDEs are much harder to use for this project)

    ✔  (Windows only) On Windows: you should install WSL:

          ●   Open PowerShell and type wsl --install
          ●   Open a wsl command line (type wsl into Start and press Enter)
          ●  Install Java JDK 17 on WSL by running this command in the WSL command window:
              sudo apt-get update && sudo apt-get upgrade && sudo apt install openjdk-17-jdk openjdk-17-jre
          ●   Do everything in this tutorial on WSL

          (It is possible without WSL, but 100 things can go wrong, so I don't recommend it)

1. Fork the project

Setting up the project is not a one-click step, but it's pretty easy.

1.1. Create a fork of the GitHub project

  • Click Fork in the top-right corner of the Gale project page

    Click "Fork" in the top-right corner of the Gale project page

  • Click Create a new fork

    Click "Create a new fork" from the dropdown menu

  • Click Create fork

    Click "Create fork"

    You will now be on the repository page for your own fork of Gale,
    (for example: on https://github.com/<username>/Gale)

1.2. Clone the repository to your machine

  • On your own fork's page, click the green Code button

    Click the green "Code" button

  • Copy the URL shown
    (which will be something like https://github.com/<username>/Gale.git)

    Copy the URL shown

  • Open IntelliJ IDEA

  • File > New > Project from Version Control...

  • In the URL field, paste the URL you copied earlier
    (for example, I would paste https://github.com/MartijnMuijsers/Gale.git)

  • Choose the directory to place Gale in


        ℹ️    (Windows only) Remember that you should use a WSL directory like    
                 \\wsl$\Ubuntu-20.04\home\martijn\minecraft_stuff\Gale    
     

  • Clone

2. Learn how Paperweight works

Now, if you don't know how Paperweight works yet, read through this simple explanation. Then, continue with the next step.

3. Get the full server source code ready to edit

3.1. Apply the patches

To apply the patches, you can use the command line, or you can use the Gradle functions in IntelliJ (by default, there is a vertical Gradle button on the right).
Normally, I use the command line, because we also need to do interactive rebases in Git anyway.
I will primarily use the command line below, except when setting up IntelliJ properly (because IntelliJ sometimes only understands Gradle projects when you build the project from within IntelliJ at least once).

  • In a command terminal, navigate to the Gale folder you just created
    (if you type ls and you see a file called .editorconfig and a file called gradlew, you are in the right folder)


        ℹ️    (Windows only) Remember that you should use a WSL command window    
     

  • Run the following command: ./gradlew applyPatches


        ⚠️   This step needs a lot of memory!    

    For some systems, you need at least 6+ GB of free RAM, but on other systems,
    you need at least 10+ GB of free RAM!
    If you do not have enough memory, you will get a very vague error saying the task failed, without an explanation.

    This happens because decompiling the vanilla and Spigot jars takes a lot of memory.
    Every time Minecraft or Spigot is updated, the jars need to be decompiled one time.

    The code should now be ready to use in the gale-api and gale-server folders.

3.1. Set up the IntelliJ project

We need to make sure the project is properly set up in IntelliJ. Maybe it immediately works on your machine. Maybe not. Follow these next steps just in case.

  • In IntelliJ, click the vertical Gradle button on the right side

    Click the vertical "Gradle" button on the right side

  • Click the refresh icon in the top left corner of the Gradle view

    Click the refresh icon in the top left corner of the Gradle view

  • Does it show a whole bunch of tasks in the Gradle view, and are there little cyan squares on the gale-api and gale-server folders on the left?

    Example of a correctly set up project in IntelliJ, with the little cyan squares

    If yes, you can skip to step 4. Make changes below.
    If no, continue with Set up Gradle and the JDK.

Set up Gradle and the JDK

If you don't see Gradle tasks, you are probably currently seeing a red error Gradle JVM option is incorrect.

In that case, follow the below steps.
(If you are seeing another error, ask for help.)

  • Click the underlined Open Gradle Settings below the error

    Click the underlined "Open Gradle Settings" below the error

  • In the bottom of window, set the Gradle JVM to the correct Java installation.

    In the bottom of window, set the "Gradle JVM" to the correct Java installation

    If you are on Windows and using WSL, you must select a Java installation on WSL.
    If you don't see the right Java installation, choose Add JDK...

  • Choose OK to save the settings.
    Gradle should immediately begin to run.
    If it doesn't start automatically, click the refresh icon in the top left corner of the Gradle view.

    The project should now be set up correctly
    (visible by the little cyan squares on the gale-api and gale-server folders)

4. Make changes

You now have all the Gale patches as commits in the gale-api and gale-server projects.
You can now edit and add patches by:

  1. Modifying or adding the commits in gale-api and gale-server (using Git interactive rebase)
  2. Doing ./gradlew rebuildPatches in the root folder
  3. Doing git commit in the root folder and describing what you changed

You should make changes on a a new branch to make a pull request.
For example, for a pull request that removes Herobrine, do git checkout -b fix/removed-herobrine.
Then push it to your fork on GitHub (with git push --set-upstream origin fix/removed-herobrine).
Then on GitHub, open a pull request for Gale from that branch.

5. When Gale updates

When there have been updates to Gale, you can pull the updates into your forked version, to make changes on top of it.

  • Go to your own fork's repository page
    (usually something like https://github.com/<username>/Gale)

  • Click the Sync fork button

    Click the "Sync fork" button

  • Click the Update branch button

    Click the "Update branch" button

  • On a command terminal in the Gale folder, check out the main branch
    (Currently the main branch is called dev, so you would do git checkout dev)

  • Do git pull

    The main branch is now up to date, so you can branch from there and make changes,
    or rebase existing branch on top of it.

© Gale 2022

Clone this wiki locally