Skip to content

Contributor Setup Instructions For MapTool

Jump to bottom Edit New page
Craig Wisniewski edited this page Feb 27, 2025 · 28 revisions

Overview

MapTool has evolved over the years to make it easier for community members to contribute source code. RPTools uses Git for source code control, Gradle for builds, Spotless for source code formatting, and GitHub as our source code repository and CI/CD platform integration with a number of 3rd party plugins.

This document contains instructions for:

  • How to install a Java JDK (Java Development Kit)
  • How to download the MapTool source code to your local workstation
  • Installing the team's preferred IDE, IntelliJ IDEA from JetBrains (however, you can use any IDE you prefer)
  • How to build MapTool on your workstation
  • How to create a feature branch
  • How to submit your feature back to RPTools for review and inclusion in future builds

Java Installation and Setup

First check which version of Java the development version of MapTool is being built with. You can do this by checking the buildSrc/shared.gradle file.

You can determine the Java version by searching for the java block in this file, it will look something like this

java {
    sourceCompatibility = JavaVersion.VERSION_XX
    targetCompatibility = JavaVersion.VERSION_XX
}

Usually both the source and target will be the same version, if they are not pick which ever is higher.

MapTool is distributed with the Temurin JDK. The easiest way to install multipe JDK versions and manage them is to use SDKMAN, once installing SDKMAN you can install the correct version with

sdkman install java-<version>-tem

SDKMAN can be installed on Linux and Mac OS. To install SDKMAN on windows you will need to either install Git Bash (which is installed with git

If you do not wish to install SDKMAN then you can install the JDK from the following link Temurin JDK. (Using SDKMAN is so much easier to manage your JVM's so it is the suggested way)

How to Clone MapTool

To either develop new MapTool features, fix bugs, or simply test unreleased code, you’ll need to make a clone of MapTool. These instructions will be specific to GitHub and MapTool but a similar process will work for TokenTool and DiceTool.

If you haven't already done so, create a GitHub account. Even if you are not a developer, you should have one to log and track issues.

You will first need to fork MapTool into your GitHub account for the instructions below to work. MapTool resides at https://github.com/RPTools/maptool.

These instructions also assume you've installed IntelliJ and the Command Line Tool plugin which allows access to the IntelliJ terminal, but these commands can be executed at the command prompt as well.

References to Settings within this document mean the project settings within the IntelliJ IDEA. On Windows and Linux, this means selecting File → Settings..., and on macOS it means selecting IntelliJ IDEA → Preferences.... (Note that IntelliJ may move the menu options described in this document, so please refer to their current documentation for specifics if you detect a mismatch.)

Run the following commands in the IntelliJ terminal window (or an OS command prompt while in the project directory):

  1. This will check out the develop branch from your repository and set it as your working branch. You can also do this via IntelliJ: right-click on maptool in the Project Explorer and select Git → Repository → Branches... and select the branch from the Local section.

    git checkout develop

  2. This verifies that when you do a pull and push you are pointing to the correct location.

    git remote -v

    The output should look something like (replace YourGitHubName with your account name):

    origin   https://github.com/YourGitHubName/maptool.git (fetch)
origin   https://github.com/YourGitHubName/maptool.git (push)

  3. This adds the RPTools MapTool repository as the upstream source for code which allows you to pull changes from the RPTools repository directly to your workstation without going through the step of syncing our code to your GitHub repository first.

    git remote add upstream https://github.com/RPTools/maptool.git

  4. Make sure the changes took effect.

    git remote -v

    Should show something like this (replace YourGitHubName with your account name):

    origin   https://github.com/YourGitHubName/maptool.git (fetch)
origin   https://github.com/YourGitHubName/maptool.git (push)
upstream https://github.com/RPTools/maptool.git (fetch)
upstream https://github.com/RPTools/maptool.git (push)

  1. This gets the latest code from RPTools. Use this to ensure your code isn't out of date with respect to the team's current code. (More on this in the Contributing Code section, below.)

    git pull -r upstream develop

    The message should show your branch is up to date with your GitHub repository. You cannot push to upstream; you must push to origin (your personal GitHub repository) and create a PR. See Why are upstream branches so useful.

  2. To push any committed changes from your local repository back to your repository on GitHub, run:

    git push -u origin develop

IntelliJ Installation and Setup

  1. Fork MapTool to your own GitHub account (see How To Clone MapTool, above).

  2. Download and install IntelliJ following the directions at https://www.jetbrains.com/idea/download.

  3. During IntelliJ installation, you will receive the following prompts (and perhaps others, if new options have been added since this was written):

    1. Theme style. Choose a theme or click Next.
    2. Plugins. We recommend leaving the defaults; click Next.
    3. Additional plugins. We recommend leaving the defaults; click Next.

  4. When installation is complete, the application will launch and the splash screen will be displayed.

  5. The following panel shows three options, "Create New Project", "Open or Import", and "Get from Version Control".

    • Choose "Get from Version Control".
    • Select "GitHub Account" on the left.
    • Enter your GitHub credentials.
    • Select your repository from the list (maptool, tokentool, or something else).
    • IntelliJ will clone (i.e., copy) your GitHub repository onto your local system.
    • By default, it will checkout the master branch. You may want to change branches; you can right-click on maptool in the Project Explorer and select Git → Repository → Branches... and then select origin/develop under the Remote Branches section.

  1. Verify project settings:

    • With the project open, go to Settings (see Settings, above), select Build, Execution, Deployment → Build Tools → Gradle, and select your JDK. If you only have one JDK installed, it should be filled in.

    • Open File → Project Structure...

      • Select Project in the sidebar and set Product SDK and Project Language Level. The Project compiler output default value does not need to be changed. If you only have one JDK installed, these fields should be filled in.

      • Select SDKs in the sidebar and select your SDK version, 17 (for Java 17). If you only have one JDK installed, it should be filled in.

Notes:

  • Most things are done via Gradle for you. But if something isn't right, always check the three places listed in Item #6, above. And remember, you can run Gradle from IntelliJ or the command line.

  • There's also a plugin to pick JDK versions from inside IntelliJ and IntelliJ can download and install them, but the team normally uses the command line or Command Line Tool plugin.

  • To switch to a new JDK, or to use it for the CLI, set the JAVA_HOME environment variable on your system (method varies by OS) and update your path to the new JAVA_HOME/bin. (Note that some Unix GUI environments are not executed in a way that causes your shell's rc file to be invoked first. If your tooling doesn't seem to be picking up the correct version of Java, this may be the issue.)

Popular Plugins

Below are a few plugins used by the RPTools developers. The instructions below use the Terminal supplied by the Command Line Tool.

  • IdeaVIM - VI editor that is (in)famous for its keystroke commands.

  • Command Line Tool - brings up a shell window within IntelliJ.

You're now ready to do some development and/or testing! Reward yourself!

Building MapTool in IntelliJ

You’ll build MapTool via the gradlew command in the Terminal window (which you may have used to get Git set up, above). Please note, Linux and Mac users will need to use ./gradlew instead, and Windows users may need to use .\gradlew.

  • Run Spotless against your local copy of MapTool source:

    gradlew spotlessApply

  • To compile and run MapTool:

    gradlew run

  • To create an installable package run:

    gradlew jpackage

    You'll find the output in the releases sub-directory. Various inputs for the build process are under the package sub-directory.

You can also add these to the run / debug configurations you can edit these configurations by selecting the Edit Configurations menu option under the Gradle Menu (the elephant icon). The values for the configuration should be

  • Name: {What ever name you want to call it}
  • Run on: Local Machine
  • Run: {The gradle command you want to run e.g. run or spotlessApply, you can have more than one like spotlessCheck run to peform formatting check before executing)
  • Gradle Project: maptool

Contributing Code

Before anything else, you should let the RPTools team know you want to work on a new feature or bug-fix. Check GitHub to see if an issue is already open for what you want to do or something similar.

  • If there is an issue open, make a comment on it saying you would like to work on it so it can be assigned to you. You'll reference that issue when you make a pull request later.
  • If you can't find an issue, create one and use the appropriate Bug or Feature template. Be sure to state that you want to work on implementing the fix or feature.

  1. Create a new branch from develop (or the feature branch you're working from). Be sure to start by checking out that branch.

    Creating a new branch is helpful in case you need to go back to a clean develop branch for testing -- just switch back to develop and delete the messed up one. :) You may find it useful to put the issue number into your branch name, particularly if you expect to work on multiple issues in rapid succession.

    You can have multiple branches based on develop at any given time.

    git checkout develop
git checkout -b some-new-idea-or-issue-number

  2. Make your amazing changes!

    It's commonly considered a best practice to commit your changes whenever your code reaches a point where it is logically complete, i.e., when it compiles and builds without errors, even if it doesn't work 100%. This allows you to "turn back time" to any intermediate point. Whether you do this or not is up to you.

  3. When your testing is done, ensure all changes are stored in your local repository.

    git commit

  4. Upload your changes to your GitHub repository.

    If this is a new branch that hasn't been pushed before, run this command:

    git push -u origin some-new-idea-or-issue-number

    If this is not the first push, you can use this shortcut version:

    git push

  5. Open a PR back to the RPTools develop branch (unless you are working on a feature branch). You do this via your web browser by visiting your repository on GitHub, selecting your branch, and then clicking the link for creating a Pull Request.

  6. If your change has conflicts, it will be your responsibility to resolve them:

    1. Checkout develop on your local repository.
    2. Pull changes from upstream develop (see previous description).
    3. Merge any updated code from develop into your branch. (If you have multiple active branches, you will need to do this step and the next for each one.)
    4. Push the changes in your branch to your repository on GitHub. This should cause the PR to automatically refresh and trigger our CI/CD process. You can visit your PR to make sure this happened.

For more information using git you can read or download the Pro Git Book for free, or Using Git in IntelliJ.

Happy Coding!

Add a custom footer
Add a custom sidebar
Clone this wiki locally