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 40-character Git commit SHA (or version tag), and at least one install step, then open a Pull Request. CI validates the Zod schema, screenshot hosts, {{ref}} checkout steps, and any optional script SHA-256 hash.

  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 dev.
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 any optional 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.
    External install scripts: If you provide an optional install script URL (.sh), it must point to a raw URL at a 40-character commit SHA or version tag and include its 64-character sha256 digest (checked by CI).
  • 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 source reference: source.ref must be a 40-character commit SHA or a version tag (never a branch name); only a 40-character commit SHA cannot be moved upstream and earns the "Source pinned" badge. Any git clone step must check out {{ref}}.
  • 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". Lists & guides (category: "resource") leave install out and get a "Read online" link instead.
  • 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, tuned for a laptop.",
  "description": "Optional long description: layout philosophy, workflow, ergonomics tips.",
  "license": "MIT",
  "version": "v1.0.0",
  "updatedAt": "2026-10-15",
  "distros": ["arch", "fedora"],
  "category": "dotfiles",
  "wm": "hyprland",
  "themeStyle": "monochrome",
  "displayServer": "wayland",
  "tags": ["waybar", "kitty", "rofi", "laptop"],
  "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": "Hyprland desktop with Waybar and two Kitty windows",
      "caption": "01_DESKTOP.RAW"
    }
  ],
  "source": {
    "repo": "https://github.com/my-handle/dots",
    "ref": "v1.0.0",
    "readme": "README.md"
  },
  "install": {
    "steps": [
      {
        "id": "deps",
        "title": "Install dependencies",
        "commands": [
          "sudo pacman -S --needed hyprland waybar kitty rofi-wayland dunst",
          "git clone --filter=blob:none https://github.com/my-handle/dots ~/dots",
          "git -C ~/dots checkout {{ref}}"
        ]
      },
      {
        "id": "dotfiles",
        "title": "Deploy dotfiles",
        "commands": [
          "mkdir -p ~/.config",
          "cp -r ~/dots/hypr ~/dots/waybar ~/dots/kitty ~/.config/"
        ]
      },
      {
        "id": "reload",
        "title": "Reload Hyprland",
        "commands": [
          "hyprctl reload"
        ]
      }
    ]
  },
  "keybindings": [
    {
      "keys": "SUPER + Return",
      "action": "exec, kitty",
      "effect": "Open terminal"
    },
    {
      "keys": "SUPER + Q",
      "action": "killactive",
      "effect": "Close window"
    }
  ]
}