starred/tuxmate
1
0
Fork 0
mirror of https://github.com/abusoww/tuxmate.git synced 2026-04-17 21:53:12 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
45ec702e74143e40c32095895e426739da2a9c6e
tuxmate/CONTRIBUTING.md
NIJAT 45ec702e74 Initial Commit
2025-12-24 07:37:01 +04:00

11 KiB
Raw Blame History

Contributing to TuxMate

Thank you for your interest in contributing! This guide covers everything you need to make meaningful contributions.

📦 Adding Applications

All applications are defined in src/lib/data.ts.

Entry Structure


Thank you for your interest in contributing! This guide covers everything you need to make meaningful contributions.

---

## 📦 Adding Applications

All applications are defined in [`src/lib/data.ts`](src/lib/data.ts).

**Entry Structure**
```typescript
{
  id: 'app-id',                     // Unique lowercase identifier (kebab-case)
  name: 'App Name',                 // Display name
  description: 'Brief description', // Max ~25 characters
  category: 'Category',             // Must be existing Category type
  iconUrl: si('icon-slug'),         // Icon using helper functions
  targets: {
    ubuntu: 'package-name',         // Exact package name for apt
    debian: 'package-name',
    arch: 'package-name',           // Use AUR package names with -bin suffix
    fedora: 'package-name',
    opensuse: 'package-name',
    nixos: 'package-name',
    flatpak: 'com.vendor.AppId',    // Full Flatpak ID
    snap: 'snap-name',              // Include --classic if needed
  },
  unavailableReason?: 'Markdown-formatted install instructions'
}

Guidelines

  • Verify package names on actual distros or Repology
  • Use -bin suffix for AUR packages when available (pre-built binaries)
  • Add --classic for Snap apps requiring classic confinement
  • Use full application IDs from Flathub for Flatpak
  • Provide helpful markdown alternatives for unavailable apps

Valid Categories

Web Browsers • Communication • Dev: Languages • Dev: Editors • Dev: Tools
Terminal • CLI Tools • Media • Creative • Gaming • Office
VPN & Network • Security • File Sharing • System

🐧 Adding Distributions

Distributions are also defined in src/lib/data.ts.

Distro Structure

{
  id: 'distro-id',
  name: 'Display Name',
  iconUrl: si('distro-slug'),
  color: '#HexColor',
  installPrefix: 'sudo pkg install -y'
}

After Adding a Distro

  1. Update src/lib/generateInstallScript.ts
  2. Add the distro case in generateInstallScript()
  3. Handle distro-specific logic (repo enabling, AUR helpers, etc.)
  4. Include proper error handling and package detection

🎨 Icon System

TuxMate uses the Iconify API for icons.

Helper Functions

Function Use Case Example
si('slug', '#color') Brand icons si('firefox', '#FF7139')
lo('slug') Colorful logos lo('chrome')
mdi('slug', '#color') Material icons mdi('console', '#57F287')
dev('slug') Developer tools dev('vscode')
sk('slug') Skill/tech icons sk('react')
vs('slug') VS Code file icons vs('file-type-shell')

Finding Icon Slugs

  • Simple Icons: simpleicons.org — use lowercase slug
  • Material Design: pictogrammers.com — use icon name
  • Fallback: Use mdi('application', '#color') with appropriate color

Requirements

  • Icons must be recognizable at 24×24px
  • Use official brand colors from Simple Icons
  • Monochrome icons require a color parameter

⚙️ Script Generation

The install script logic lives in src/lib/generateInstallScript.ts.

Key Features to Maintain

  • Package detection for already-installed software
  • AUR handling with auto-install of yay helper
  • RPM Fusion auto-enabling for Fedora
  • Parallel installation support for Flatpak
  • Exponential backoff retry for network failures
  • Progress bars with ETA and colored output

Testing Script Changes

# Generate and test a script
npm run dev
# Select packages → Copy script → Test in VM/container

# Quick testing with Docker
docker run -it archlinux bash
docker run -it ubuntu bash

💻 Development Workflow

Setup

git clone https://github.com/abusoww/tuxmate.git
cd tuxmate
npm install
npm run dev

Before Committing

npm run lint          # Check for errors
npm run lint -- --fix # Auto-fix issues
npm run build         # Verify production build

Code Standards

  • Use proper TypeScript types, avoid any
  • Follow existing code style (Prettier defaults)
  • Keep React components focused and reusable
  • Add new apps in alphabetical order within their category

🔀 Pull Request Guidelines

Branch Naming

feature/add-app-name
feature/add-distro-name
fix/description-of-fix
docs/update-readme

PR Checklist

  • Tested locally with npm run dev
  • Production build passes: npm run build
  • Lint passes: npm run lint
  • Package names verified on distros or Repology
  • Icons display correctly at small sizes
  • Unavailable reasons include helpful alternatives

Commit Format

type: short description

- Details if needed
- Fixes #123

Types: feat fix docs style refactor test chore

🐛 Reporting Issues

Bug Reports — Include:

  • Browser & OS (e.g., Firefox 120 on Arch Linux)
  • Steps to reproduce (numbered list)
  • Expected vs actual behavior
  • Console errors (F12 → Console tab)
  • Screenshots if UI-related

Feature Requests — Include:

  • Use case and why it's needed
  • Proposed solution
  • Alternatives considered

❓ Questions?

Open a Discussion or create an Issue.

{ id: 'app-id', // Unique lowercase identifier (kebab-case) name: 'App Name', // Display name description: 'Brief description', // Max ~25 characters category: 'Category', // Must be existing Category type iconUrl: si('icon-slug'), // Icon using helper functions targets: { ubuntu: 'package-name', // Exact package name for apt debian: 'package-name', arch: 'package-name', // Use AUR package names with -bin suffix fedora: 'package-name', opensuse: 'package-name', nixos: 'package-name', flatpak: 'com.vendor.AppId', // Full Flatpak ID snap: 'snap-name', // Include --classic if needed }, unavailableReason?: 'Markdown-formatted install instructions' }


**Guidelines**
- Verify package names on actual distros or [Repology](https://repology.org/)
- Use `-bin` suffix for AUR packages when available (pre-built binaries)
- Add `--classic` for Snap apps requiring classic confinement
- Use full application IDs from [Flathub](https://flathub.org) for Flatpak
- Provide helpful markdown alternatives for unavailable apps

**Valid Categories**

Web Browsers • Communication • Dev: Languages • Dev: Editors • Dev: Tools Terminal • CLI Tools • Media • Creative • Gaming • Office VPN & Network • Security • File Sharing • System


---

## 🐧 Adding Distributions

Distributions are also defined in [`src/lib/data.ts`](src/lib/data.ts).

**Distro Structure**
```typescript
{
  id: 'distro-id',
  name: 'Display Name',
  iconUrl: si('distro-slug'),
  color: '#HexColor',
  installPrefix: 'sudo pkg install -y'
}

After Adding a Distro

  1. Update src/lib/generateInstallScript.ts
  2. Add the distro case in generateInstallScript()
  3. Handle distro-specific logic (repo enabling, AUR helpers, etc.)
  4. Include proper error handling and package detection

🎨 Icon System

TuxMate uses the Iconify API for icons.

Helper Functions

Function Use Case Example
si('slug', '#color') Brand icons si('firefox', '#FF7139')
lo('slug') Colorful logos lo('chrome')
mdi('slug', '#color') Material icons mdi('console', '#57F287')
dev('slug') Developer tools dev('vscode')
sk('slug') Skill/tech icons sk('react')
vs('slug') VS Code file icons vs('file-type-shell')

Finding Icon Slugs

  • Simple Icons: simpleicons.org — use lowercase slug
  • Material Design: pictogrammers.com — use icon name
  • Fallback: Use mdi('application', '#color') with appropriate color

Requirements

  • Icons must be recognizable at 24×24px
  • Use official brand colors from Simple Icons
  • Monochrome icons require a color parameter

⚙️ Script Generation

The install script logic lives in src/lib/generateInstallScript.ts.

Key Features to Maintain

  • Package detection for already-installed software
  • AUR handling with auto-install of yay helper
  • RPM Fusion auto-enabling for Fedora
  • Parallel installation support for Flatpak
  • Exponential backoff retry for network failures
  • Progress bars with ETA and colored output

Testing Script Changes

# Generate and test a script
npm run dev
# Select packages → Copy script → Test in VM/container

# Quick testing with Docker
docker run -it archlinux bash
docker run -it ubuntu bash

💻 Development Workflow

Setup

git clone https://github.com/abusoww/tuxmate.git
cd tuxmate
npm install
npm run dev

Before Committing

npm run lint          # Check for errors
npm run lint -- --fix # Auto-fix issues
npm run build         # Verify production build

Code Standards

  • Use proper TypeScript types, avoid any
  • Follow existing code style (Prettier defaults)
  • Keep React components focused and reusable
  • Add new apps in alphabetical order within their category

🔀 Pull Request Guidelines

Branch Naming

feature/add-app-name
feature/add-distro-name
fix/description-of-fix
docs/update-readme

PR Checklist

  • Tested locally with npm run dev
  • Production build passes: npm run build
  • Lint passes: npm run lint
  • Package names verified on distros or Repology
  • Icons display correctly at small sizes
  • Unavailable reasons include helpful alternatives

Commit Format

type: short description

- Details if needed
- Fixes #123

Types: feat fix docs style refactor test chore

🐛 Reporting Issues

Bug Reports — Include:

  • Browser & OS (e.g., Firefox 120 on Arch Linux)
  • Steps to reproduce (numbered list)
  • Expected vs actual behavior
  • Console errors (F12 → Console tab)
  • Screenshots if UI-related

Feature Requests — Include:

  • Use case and why it's needed
  • Proposed solution
  • Alternatives considered

❓ Questions?

Open a Discussion or create an Issue.

Reference in New Issue View Git Blame Copy Permalink