Kaleidoscope Contributors' Guide

A primer on contributing to Kaleidoscope

Introduction

This article will give prospective contributors a set of procedures that they can use to contribute code to Kaleidoscope and its core plugins (and other modules). Because of its plugin architecture, the code for Kaleidoscope's firmware is divided up into many different repositories on GitHub, and that can prove difficult to manage, even for people with experience using simpler git repository structures. This is not the only way, nor even the best way for everyone, but it is one method for managing the somewhat complex repository tree that contains Keyboardio's Kaleidoscope code.

The Kaleidoscope-Bundle-Keyboardio repository tree

All of the Kaleidoscope code is accessible through a single repository: Kaleidoscope-Bundle-Keyboardio, which includes many other repositories as git submodules. If you haven't already done so, start by cloning that repository like this:

git clone --recurse-submodules https://github.com/keyboardio/Kaleidoscope-Bundle-Keyboardio.git

Not surprisingly, the --recurse-submodules option causes git to check out all the submodules. Alternatively, this can be done in two separate steps:

git clone https://github.com/keyboardio/Kaleidoscope-Bundle-Keyboardio.git
git submodule --init --recursive

Either way, you'll now have a copy of Kaleidoscope-Bundle-Keyboardio and all of its submodules, including Kaleidoscope and all of the core Kaleidoscope plugins (named Kaleidoscope-*). Assuming you've got Arduino installed, the last thing you need to do is link Kaleidoscope-Bundle-Keyboardio to the Arduino build directory on your computer (instructions in the README).

Forking a submodule and managing multiple remotes

So, you've now got a copy of Kaleidoscope-Bundle-Keyboardio, and with it, Kaleidoscope and all of the core plugins, and you're looking through the code in one of those submodules, and you see something that you want to change. Now comes the tricky part.

Suppose you want to change something in Kaleidoscope, and you want to test it out by building Model01-Firmware. If you make a separate copy of Kaleidoscope elsewhere, that won't get used in your firmware build unless you take pains to change the build parameters.

Branch management

Submitting pull requests