SplashKit Expansion

Contributing to splashkit-core

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.

If you haven’t already, ensure you have setup your work environment by following the Setting up your environment guide

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