diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 001d96e9..99ce571c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -94,7 +94,7 @@ syllables per word. For more information, see [official instructions to install nvm](https://github.com/nvm-sh/nvm#installing-and-updating), a Node version manager. Then, run the following to install and use the repository's Node version: - ```sh + ```shell nvm install nvm use ``` @@ -104,7 +104,7 @@ syllables per word. For more information, see 1. Install all dependencies - ```sh + ```shell npm install ``` @@ -124,7 +124,7 @@ syllables per word. For more information, see 1. Install curl - ```sh + ```shell sudo apt-get install curl ``` @@ -132,7 +132,7 @@ syllables per word. For more information, see [official instructions to install nvm](https://github.com/nvm-sh/nvm#installing-and-updating), a Node version manager. Then, run the following to install and use the repository's Node version: - ```sh + ```shell nvm install nvm use ``` @@ -142,7 +142,7 @@ syllables per word. For more information, see 1. Install all dependencies - ```sh + ```shell npm install ``` diff --git a/src/content/docs/Products/SplashKit/Splashkit Expansion/Documentation/onboarding-guide.mdx b/src/content/docs/Products/SplashKit/Splashkit Expansion/Documentation/onboarding-guide.mdx new file mode 100644 index 00000000..fde18b81 --- /dev/null +++ b/src/content/docs/Products/SplashKit/Splashkit Expansion/Documentation/onboarding-guide.mdx @@ -0,0 +1,233 @@ +--- +title: SplashKit Expansion Onboarding Guide +sidebar: + label: SK Expansion Onboarding Guide + order: 1 +--- + +## 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](https://splashkit.io/installation/windows-wsl). 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](https://splashkit.io/installation/windows-wsl/step-3) + +### Installing Git + +Now Git must be installed to WSL. Follow the Microsoft installation instructions: +[Install Git](https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-git). GitHub's Git Cheat +Sheet is useful for both installation and usage of Git: +[GitHub Git Cheat Sheet](https://education.github.com/git-cheat-sheet-education.pdf) + +### 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](https://learn.microsoft.com/en-us/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](https://github.com/splashkit/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](https://thoth-tech.netlify.app/products/splashkit/splashkit-website/onboarding/01-setting-up). + +### Cloning splashkit-core Repository + +Open a WSL terminal and change directory to your home with: + +```shell +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: + +```shell +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: + +```shell +cd splashkit-core +``` + +Check the current branch with: + +```shell +git branch +``` + +Create a new branch using the current branch as a base: + +```shell +git branch {new branch name} +``` + +Swap to new branch with: + +```shell +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: + +```shell +cd +cd splashkit-core/projects/cmake +cmake -G "Unix Makefiles" . +make +``` + +The associated macOS and Linux commands can be found here: +[CONTRIBUTING](https://github.com/thoth-tech/splashkit-core/blob/develop/CONTRIBUTING.md) + +### Running the Test Programs + +To run the test programs, open a WSL terminal and enter: + +```shell +cd +cd splashkit-core/bin +``` + +Then for sktest: + +```shell +./sktest +``` + +Or for skunit_tests: + +```shell +./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: + +```shell +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: + +```shell +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](https://thoth-tech.netlify.app/products/splashkit/splashkit-website/onboarding/03-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](https://thoth-tech.netlify.app/products/splashkit/splashkit-website/onboarding/05-peer-review) + +### 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](https://thoth-tech.netlify.app/products/splashkit/splashkit-website/onboarding/07-planner-board) + +## 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](https://thoth-tech.netlify.app/products/splashkit/splashkit-website/onboarding/02-troubleshooting) + +### 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: + +```shell +cd +cd splashkit-core +git submodule update --init --recursive +```