Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
147 lines (108 loc) · 7.47 KB

CONTRIBUTING.md

File metadata and controls

147 lines (108 loc) · 7.47 KB

Contributing to the tosu repository of overlays

Hi there! Thank you for considering contributing to the tosu overlays repository. Before you submit your overlay, please read the following guidelines to ensure a smooth contribution process.

Table of Contents

 

Getting Started

If you are new to GitHub or this repository, follow these steps to get your overlay submitted. You can use quickstart as a template for your own.

Fork & Clone

  1. Fork this repository to your own GitHub account.
  2. Clone your fork locally: git clone https://github.com/tosuapp/counters.git.
  3. Create a new branch for your overlay: git checkout -b feat/my-fancy-overlay.

Development & Testing

  1. In your tosu ./static folder, create a new folder following our naming conventions.
  2. Develop your overlay using any framework of your choice.
  3. Bundle your overlay into pure HTML, CSS and JavaScript. (optional, if you didn't use frameworks)
  4. Test your overlay using tosu and ensure it works as expected.

Submitting

  1. Copy your finished overlay folder into the counters/ directory of your local repository.
  2. Commit your changes with a clear message.
  3. Push to your fork: git push origin feat/my-fancy-overlay.
  4. Open a Pull Request against our master branch.

Review Process

Once submitted, your Pull Request will undergo a review by our team.
We usually require approval from two maintainers before an overlay is merged to ensure quality and compatibility.
We may ask for small adjustments regarding performance or file structure during this period.

Once the PR is merged, your overlay will shortly appear in the official tosu dashboard for all users.

 

Rules

To maintain quality and consistency across all overlays, please adhere to the following rules when submitting a Pull Request.

File Structure & Naming

Each overlay must be self-contained within its own directory under the counters/ folder.

Folder Format {overlay_name} by {author_name}

The {overlay_name} in the folder title must match the name defined in your metadata.txt.

Metadata Requirements

For your overlay to display correctly in the tosu dashboard, a metadata.txt file is required.
Refer to this wiki page for a detailed guide on structuring this file.

Websocket Filters

To maintain optimal performance, all overlays must use websocket filters.
This prevents unnecessary data from being sent over the socket and reduces the load on the user's system.

Please refer to our Wiki Guide on Filters for a detailed explanation of how to implement them.

 

Tip

While running tosu, you can visit http://127.0.0.1:24050/json/v2 to see what the websocket sends. This helps you understand exactly what data is available for your overlay.

Dependencies & Offline Support

Our software is designed to run in offline environments. All assets must be bundled locally.

  • Include all libraries, fonts, and images within your folder. No external CDNs.
  • Third-party libraries must be minified. (such as: jQuery, Chart.js, countUp.js, etc.)
  • The tosu socket should remain unminified and must be up to date at the time of your PR.

Code Quality & Standards

We value readability and long-term maintainability.
While we don't enforce a strict style guide, we expect the following:

  • Consistent indentation and spacing.
  • Self-explanatory variable and function names.
  • Consistency in coding style throughout your code.
  • English for all documentation and code comments.
  • No commented code, unused variables, and dead functions.
  • Comments only providing the "why" (context), not the "how" (line-by-line explanation).

Generative AI Policy

We welcome the use of AI tools to assist in your workflow. However, fully AI-generated submissions will be rejected.
We require human oversight and a clear understanding of the code you submit.

Git & Commit Standards

We do not enforce strict naming conventions, but we do require a level of professionalism to keep the project history readable.
You can visit Chris Beams' guide on writing good commit messages for more information.

Recommended Resources

If you are new to development or just want to ensure your contribution meets our standards, we recommend checking out these guides:

Licensing

Repository License Structure

Because this repository serves as a community collection, there is no single global license.
Each overlay is treated as an individual project and remains the intellectual property of its respective author.

Licensing Your Work

We encourage you to license your contribution to define how others can use and modify it.
To do so, simply include a LICENSE file within your overlay's specific folder.

Recommended Licenses:

  • MIT: Simple and permissive.
  • GNU GPL v3: Ensures derivative works stay open-source.
  • Apache 2.0: Includes explicit patent rights.
  • Creative Commons (e.g., CC BY-SA): Good for design-heavy overlays.

If you are unsure which to pick, visit choosealicense.com for guidance.

Maintenance & Modifications

Important

By submitting your overlay, you allow the tosu team to apply urgent modifications for performance, security, or compatibility without prior notice. For any other non-essential changes or community improvements, we will attempt to contact you for approval before merging. Your original authorship will always be preserved in the metadata and version history.

 

 

You've reached to bottom of the contributing guide. Jump to top