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:
cdcd splashkit-core/projects/cmakecmake -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:
cdcd 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:
cdcd splashkit-core/projects/cmakemake
If any files were created or deleted, the CMake files need to be regenerated. In that case use:
cdcd splashkit-core/projects/cmakecmake -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