Skip to content

Contributor Setup Instructions For MapTool

Jump to bottom Edit New page
marlon bilbao hernandez edited this page Jul 21, 2022 · 26 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 17 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 17 Installation and Setup

As of December 15th, 2021 we are using Java 17. We package a JVM with our tools so normal tool users don’t need to work about a JDK install. However, if you’re coding or testing unreleased code you’ll need to make sure your development environment points to Open JDK 17.

The instructions below assume you will download Java 17 into a directory. If your OS has an installation manager that can install Java 17, you can use that instead. (For example, Linux users may want to use apt or yum or whatever tool their distribution provides, and macOS users may want to use brew or fink.)

  1. Download OpenJDK 17 from https://adoptopenjdk.net/.
  2. Pick JDK 17 and Hotspot for the JVM from the Open JDK install.
  3. Install the JDK per the instructions.

If this is going to be the Java used for all your applications you can modify your JAVA_HOME and update your PATH to include JAVA_HOME/bin at the system level. If not, you’ll need to create a script you can run to use Java 17 via a command-line interface. Modifying these will require a reboot on Windows. Mac and Linux users should simply need to source their shell's rc script (for example, .bashrc for Bash and .zshrc for Zsh). (Linux users may want to take advantage of the alternatives support provided by Linux. Configuring alternatives will not be discussed here.)

Note that the method for setting your Java environment variables is OS-dependent but a quick search should yield the steps for your OS and version. Search for setting java_home and path and select the option that matches your OS.

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.

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.

Happy Coding!

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