Skip to content

Latest commit

 

History

History
128 lines (101 loc) · 5.73 KB

CONTRIBUTING.md

File metadata and controls

128 lines (101 loc) · 5.73 KB
Raw

Contributing

Thanks for helping with SlimeVR! This document explains what to know when contributing.

We are most active on Discord, come chat with us if you have any questions or want to hang out! 😎

Setting up the development environment

We use PlatformIO as our build tooling and rely on Git for version control. There are instructions to set all of this up here.

Using third-party code

Often you will want to use or reference third-party code. You should not just copy-paste code from random libraries! There are several reasons for this:

  • It is not clear when/where the code originated from.
  • The original code's license needs to be kept intact.
  • It removes the ability to update our code when the original updates.
  • It makes it harder for us to maintain the code, because we don't know what has changed from the original!

Instead, we will want to do the following:

  1. Check that the dependency has a permissive license.
  2. (Optional) Fork the dependency if it needs any modification.
  3. Add the dependency via PlatformIO.

Check the license

The SlimeVR firmware is under the MIT License and also is intended to be permissively licensed. This means that we will not accept contributions that include code from any viral software licenses. If you do not know what that means, here is a breakdown of some common software licenses:

Fine to use:

  • MIT
  • Apache 2.0
  • BSD

Will not be accepted:

  • GPLv3 or v2
  • LGPL
  • No license

This includes the license of any code that your dependency depends on! If you are ever unsure, feel free to ask us in our Discord.

(Optional) Fork the dependency

When you want to use the depdendency, you should ask yourself: "Can I simply call the functions/classes in the dependency from my code, or do I actually need to modify the source code of the original files"? If the answer is "I need to modify the original files", then you will need to fork the dependency so that your modifications are clear.

Note If you have never forked on GitHub before, a fork is basically a copy of a library that maintains the original's history. This means that any changes you commit in your fork will show up as changes against the original. We can even update these changes as the original changes!

To create a fork in GitHub, simply go to the original library and click this button: Now clone your repo to your computer. From this point forward, any changes that you make while working on your fork will have their Git history preserved and linked to the original when you commit those changes.

We will likely ask you to transfer ownership of the fork to the SlimeVR organization if your PR is going to be merged.

Adding the dependency

PlatformIO provides us a helpful way to do dependency management. Here we provide the basic workflow you can follow, but you can refer to the PlatformIO documentation on dependecies for more details.

PlatformIO gives us a helpful way to do dependency management, which you can read an overview of here. But to save you time, we have outlined the basic workflow for you.

There is a field called lib_deps in the platformio.ini file that describes the list of dependencies in the code. These are third-party libraries located outside the main firmware git repo. You want to add your dependency to this list. The full list of options for this field is outlined here, but for simplicity, there are a few common ways of giving dependencies:

[env]
lib_deps=
  bblanchon/ArduinoJson@6.9.12
  https://github.com/Some/Dependency.git#v1.2.3
  symlink://C:/path/to/the/library

In order, these dependencies do the following:

  1. Adds a dependency on version 6.9.12 of the ArduinoJson library by bblanchon. This library was uploaded to the PlatformIO package registry which contains many popular libraries intended for use with PlatformIO.
  2. Adds a dependency to a Git repo located at https://github.com/Some/Dependency and uses the commit tagged as v1.2.3. This could also have been a branch name, or a commit hash.
  3. Links to a folder locally on your computer with the path C:/path/to/the/library. This is useful when testing your code locally where you want to make changes in your fork (which is checked out at that path), but you don't want to have to constantly commit and push to your fork just to get the changes usable by the firmware.

Note If you have forked the dependency instead of using it as-is, we recommend using the symlink:// approach while developing locally, and then using the Git approach when submitting your code for a pull request. This is because while developing locally, you will want to test out frequent changes and won't want to have to push constantly to Git and have PlatformIO constantly retrieve those changes. However, for anyone else to be able to use your code, it needs to be in a Git repository rather than a symlink.

Once you are done doing local testing and are ready to submit a PR, you can push whatever changes you made to the forked dependency to its repository, and switch the firmware's lib_deps back to the Git url.

Dont forget that your fork will need to be pushed and publicly viewable on GitHub for us to be able to use and review it!