0xTsoa
Contribution Guide

SUBMIT A CONFIGURATION TO
0xTsoa

Zero-database submission pipeline: submit a GitHub Issue Form or open a Pull Request against configs/<author>/<slug>.json.

Method 1 • Direct Pull Request

DEV_RECOMMENDED

Add configs/<github-handle>/<slug>.json with a category, a pinned Git commit or tag and at least one install step, then open a Pull Request. CI validates the Zod schema, image hosts, and script checksums.

  1. Fork the
    0xTsoa
     repository on GitHub.
  2. Create the file configs/<your-handle>/<slug>.json.
  3. Validate locally with npm run validate.
  4. Open your Pull Request towards main.
View JSON Schema

Method 2 • GitHub Issue Form

ZERO_CODE

Fill out the structured GitHub Issue Form (desktop part, screenshots, install commands). The issue-to-config Action computes the script SHA-256 digest, validates the JSON entry, and opens a Pull Request.

Pick the desktop part, paste your install commands (dependencies, deploy, reload) and screenshots. Our GitHub Action builds the JSON, computes the SHA-256 of any install script, and opens the Pull Request with CI validation.
Open GitHub Issue Form ↗

CI VALIDATION & SECURITY RULES

  • 1.
    Reproducible install scripts: If you provide an install script URL (.sh), it must point to a full 40-character commit SHA or immutable tag, and include a verified sha256 checksum.
  • 2.
    Allowed screenshot hosts: Screenshots must be hosted on:raw.githubusercontent.com, user-images.githubusercontent.com, private-user-images.githubusercontent.com, github.com, i.imgur.com, i.redd.it, codeberg.org, gitlab.com.
  • 3.
    Pinned README reference: The source.ref property must be a fixed tag or commit for deterministic builds and historical preservation.
  • 4.
    Installation is required: install.steps needs at least a deps step (packages or clone); dotfiles and reload are optional. They render as "02. Installation & Deployment".
  • 5.
    Desktop part & tags: set category to one of dotfiles, wm, bar, widgets, launcher, notifications, dock, icons, cursors, gtk-theme, colorscheme, login, lockscreen, boot, extension, tool, resource. Tags name components and features, never the WM, distro or theme style (those are filters already).

Standardized JSON Format Example

{
  "$schema": "../../schema/config.schema.json",
  "name": "My Clean Setup",
  "author": {
    "name": "My Name",
    "github": "my-handle"
  },
  "lang": "en",
  "summary": "Minimal Hyprland desktop with Waybar and Kitty on Arch Linux.",
  "description": "Optional long description: layout philosophy, workflow, ergonomics tips.",
  "license": "MIT",
  "version": "v1.0.0",
  "updatedAt": "2026-10-15",
  "distros": [
    "arch"
  ],
  "category": "dotfiles",
  "wm": "hyprland",
  "themeStyle": "monochrome",
  "displayServer": "wayland",
  "tags": [
    "hyprland",
    "arch"
  ],
  "specs": {
    "bar": "Waybar",
    "terminal": "Kitty",
    "launcher": "Rofi",
    "notifications": "Dunst",
    "theme": "Paper Monochrome",
    "shell": "zsh",
    "editor": "Neovim"
  },
  "screenshots": [
    {
      "url": "https://raw.githubusercontent.com/my-handle/dots/v1.0.0/preview.png",
      "alt": "Screenshot of my desktop",
      "caption": "01_DESKTOP.RAW"
    }
  ],
  "source": {
    "repo": "https://github.com/my-handle/dots",
    "ref": "v1.0.0",
    "readme": "README.md"
  },
  "install": {
    "script": {
      "url": "https://raw.githubusercontent.com/my-handle/dots/v1.0.0/install.sh",
      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "shell": "bash"
    },
    "steps": [
      {
        "id": "deps",
        "title": "Install dependencies",
        "commands": [
          "sudo pacman -S --needed hyprland waybar kitty rofi-wayland dunst"
        ]
      },
      {
        "id": "dotfiles",
        "title": "Deploy dotfiles",
        "commands": [
          "git clone --branch v1.0.0 https://github.com/my-handle/dots ~/dots",
          "cp -r ~/dots/.config/* ~/.config/"
        ]
      },
      {
        "id": "reload",
        "title": "Reload Hyprland",
        "commands": [
          "hyprctl reload"
        ]
      }
    ],
    "packages": []
  },
  "keybindings": [
    {
      "keys": "SUPER + Return",
      "action": "exec, kitty",
      "effect": "Open terminal"
    },
    {
      "keys": "SUPER + Q",
      "action": "killactive",
      "effect": "Close window"
    }
  ]
}