Skip to content

Contributing

During the course of using IdleKit there could be situations where you decide to patch functionality, for features or bugs, in order to deliver your game. This document outlines why you might want to contribute your changes back to IdleKit and how to do so.

Why Contribute?

Contributing changes benefits you by shifting long-term maintenance work from you to the IdleKit team. As long as what you are contributing is common enough to be shipped in an IdleKit release, you can contribute it.

There is no pressure or expectation to contribute patches. Only do so if you feel it is a valuable use of your time.

Where To Contribute

IdleKit is split into several repositories based on the provided functionality, which are all enumerated below. All repositories are private and hosted on GitHub. To contribute, you will need to be given access to fork the repository in order to create pull requests using our external contributors workflow.

GitHub Repository Description
IdleKit The primary IdleKit repository.
Idlekit Showcase Sample project showcasing IdleKit functionality
Legal User interactions with legal documents, like accepting Terms of Service.

How To Contribute

There are a few details you should provide so that reviewing patches is easy and fast. These details are available within the external contributor Pull Request template, and listed here:

  • What problem is your change solving?
  • Is there a small example of this problem?
  • What is your solution to the problem?
  • Is there a small example showing this solution?
  • Have you updated the documentation, if necessary?
  • Have you updated or included unit tests, if necessary?

Once you have answers to these details you can create a Pull Request.

Patch Sizes

Keep patch size in mind for your contributions: the smaller the patch the quicker it is for the IdleKit team to review and integrate it into a release. If you have several patches that you want to contribute, make as many smaller Pull Requests as necessary instead of a single large Pull Request.

Patch Branches

Your patch branches can be named whatever you like, but you should ensure that your work is based off of the external branch within any IdleKit repository.

The external branch is where accepted external contributions sit until they are integrated into a release. If your patch doesn't merge into the external branch, it won't make it into a release.

Using Forks & The External Contributor Template

This section is an example of how to create a Pull Request via GitHub using a fork of the IdleKit Analytics repository and the external contributors Pull Request template.

When you are ready to contribute your patch, find your patch branch within your IdleKit repository fork.

A repository fork with a patch to contribute

Click the "Compare & Pull Request" button. GitHub will automatically set the "base" of the Pull Request to the IdleKit repository and set the "compare" of the Pull Request to your fork and branch.

The default view of a fork pull request

Make sure you change the IdleKit target branch to external.

Target the "external" branch

To help you create your Pull Request, we have an external contributors template which GitHub can automatically load for you. Unlike Issue templates, GitHub doesn't yet support selecting a Pull Request template, so you will need to change your Pull Request's URL. At this point in the example, the URL is:

https://github.com/Idlekit/idlekit-analytics/compare/external...esg-starulli:esg-starulli-patch-1?expand=1

To load the template add the "template" parameter to the URL, give it the value "external.md", then hit enter to reload the page:

https://github.com/Idlekit/idlekit-analytics/compare/external...esg-starulli:esg-starulli-patch-1?expand=1&template=external.md

After this your Pull Request will contain the external contributor template.

The pull request filled with the template

Once you've filled in the details you can create your Pull Request and use your private Slack channel with the IdleKit team to notify us. Someone from the IdleKit team will review it. At this point the process is a standard code review where changes may be requested to maintain consistency.

Your change will eventually be merged and scheduled it to be integrated into an upcoming release if it is considered something that is common enough to be a benefit to many.