Tutorial: Contributing

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 must have installed Git (or a Git client like GitHub Desktop, Sourcetree or IntelliJ IDEA).

    ✔  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)

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 Create a new 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

  

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

  

• 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

• 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)

• 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 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?

  

  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

  

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

  

  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 Update branch button

  

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

• 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 2023}