SplashKit Expansion Onboarding Guide

Note

This guide is the original onboarding guide that was created for this project, but this information has been moved to the SplashKit-wide GitHub Guide, which may be more up-to-date.

This guide is here as well in case it is easier to use.

Introduction

This guide will cover all the steps required to get contributing to the splashkit-core repository. Feel free to skip steps which you have already completed or are familiar with.

Installing WSL

WSL is a built-in Linux distribution virtual machine for Windows. splashkit-core will be installed to the Linux distribution. The official SplashKit installation instructions can be found here: Windows (WSL) Installation Overview. This guide has been tested with the default Ubuntu distribution, but others may also work.

Installing Visual Studio Code

Once WSL has been installed to Windows, Visual Studio Code needs to be installed to WSL. The SplashKit documentation explains the process: Install Visual Studio Code

Installing Git

Now Git must be installed to WSL. Follow the Microsoft installation instructions: Install Git. GitHub’s Git Cheat Sheet is useful for both installation and usage of Git: GitHub Git Cheat Sheet

Installing Windows Terminal (optional)

Windows Terminal is an updated Command Prompt with many useful features. It is not mandatory to install, however it is recommended due to its ease of use. More information about Windows Terminal can be found here: Windows Terminal.It can be installed through the Microsoft Store.

By default, new tabs will open as a Command Prompt, with WSL terminals being accessible with the down-arrow. Since WSL will be used so frequently, there is the option to change the default tab to WSL. Open the settings by clicking the down arrow and selecting ‘Settings’. In the ‘Startup’ tab, ‘Default profile’ allows you to change the default tab type to WSL.

Setting Up splashkit-core

Now that WSL is fully configured, it is time to install the splashkit-core repository.

Forking splashkit-core Repository

A fork is a copy of a repository which allows for independent development without interfering with the primary repository itself. To create a personal fork of splashkit-core, navigate to GitHub splashkit-core and click ‘Fork’. On the next page, keep the default name and click ‘Create fork’.

The following guide for the SplashKit Website has useful information regarding forks and branches which can be adjusted for splashkit-core by substituting repository names: Get Your Environment Set Up.

Cloning splashkit-core Repository

Open a WSL terminal and change directory to your home with:

cd

Note that this guide clones the repository to the home directory, but feel free to move its location. Now initiate the clone process of your fork with:

git clone --recursive -j2 https://github.com/{user name}/splashkit-core.git

splashkit-core contains multiple submodules (separate repositories which splashkit-core depends upon). The --recursive argument ensures that the submodules are also downloaded when calling clone. Wait for the download to complete before continuing to the next step.

Contributing to splashkit-core

It is now time to start fixing bugs and adding functionality to splashkit-core.

Creating Branch

When modifying the repository, changes should be logically grouped together onto separate branches. To create a branch, open a WSL terminal and navigate to the splashkit-core folder with:

cd splashkit-core

Check the current branch with:

git branch

Create a new branch using the current branch as a base:

git branch {new branch name}

Swap to new branch with:

git checkout {new branch name}

Now that a new branch is created and active, development can begin.

Building the Test Programs

You cannot create new programs with splashkit-core as you do when using the traditional SplashKit library. Instead, two programs are generated which can be configured to test its functionality: sktest and skunit_tests. They are built with CMake using a preconfigured CMakeLists.txt file. Open a WSL terminal and enter:

cd
cd splashkit-core/projects/cmake
cmake -G "Unix Makefiles" .
make

The associated macOS and Linux commands can be found here: CONTRIBUTING

Running the Test Programs

To run the test programs, open a WSL terminal and enter:

cd
cd splashkit-core/bin

Then for sktest:

./sktest

Or for skunit_tests:

./skunit_tests

Making Changes

sktest is built with the .cpp files from ~/splashkit-core/coreskd/src/test/. To add your own tests, modify one or more of the files such as test_animation.cpp.

skunit_tests is built with the .cpp files from ~/splashkit-core/coreskd/src/test/unit_tests/. When it runs, all unit tests from all files in this folder are executed. Additional files can be added to this folder if necessary. If adding a new file, copy the structure from one of the existing unit test files. Critically, #include "catch.hpp" must be present in the file for it to be compiled into skunit_tests. Beyond that, the hierarchy of, TEST_CASE > SECTION > ASSERTION should be followed to improve readability and tracing of errors.

Testing Changes

If a change is made to the code, the test programs need to be rebuilt. In a WSL terminal enter:

cd
cd splashkit-core/projects/cmake
make

If any files were created or deleted, the CMake files need to be regenerated. In that case use:

cd
cd splashkit-core/projects/cmake
cmake -G "Unix Makefiles" .
make

Documenting Changes

Local changes can be tested by building and running the test programs. However, once changes are to be submitted for review, they need to be staged, committed and pushed. It is good practice to perform multiple smaller commits with meaningful descriptions rather than a single monolithic commit. In addition, pushing commits to GitHub provides a layer of backup in case of local machine failure.

Creating a Pull Request

Once you have completed work on a particular branch, a pull request (PR) can be made. At this point there are now three relevant splashkit-core repositories at play: splashkit-core itself, thoth-tech’s fork, and your personal fork. During trimester, PRs should be made against the thoth-tech fork. The PR template provides a framework for how to structure the associated PR documentation.

The following guide details how to create PRs for the SplashKit Website. The same instructions can be used for splashkit-core by simply changing the repository name: How to Create a Pull Request.

Responding to Peer Reviews

If changes are requested during a PR review, pushing further commits to the same branch will automatically be added to the PR.

Performing Peer Reviews

A critical component to SplashKit development is the process of reviewing your peers’ PRs and providing constructive feedback. This process has been detailed in the following guide: A Guide to Doing Peer Reviews

Planner Board

The planner board is used to coordinate tasks while they are being completed and reviewed. The following guide details the procedure and etiquette which is expected while using the planner board: Planner Board Ettiquete

Troubleshooting

Solutions for common issues can be found below. Be sure to also check the following page for help troubleshooting: Guide to resolving Common Issues

Empty Translator folder

If the translator folder is empty, it may be due to an issue with the submodules. In an WSL terminal, enter the following:

cd
cd splashkit-core
git submodule update --init --recursive