Contributing to Tux¶

Thank you for your interest in contributing to Tux. This guide covers setup, workflow, and how to submit changes. For deeper dives, see Git best practices, branch naming, and Code review.

We welcome contributions of all kinds: bug fixes, features, and documentation improvements.

Contributing Workflows¶

Tux supports both organization members and external contributors.

Organization Members¶

• Clone the main repository: git clone https://github.com/allthingslinux/tux.git && cd tux
• Create feature branches in the main repo and push to origin

External Contributors¶

• Fork the repository (Fork button → choose your account; you can leave "Copy the main branch only" checked).
• Clone your fork: git clone https://github.com/yourusername/tux.git && cd tux
• Add upstream and verify:

git remote add upstream https://github.com/allthingslinux/tux.git
git remote -v

• Push branches to your fork (origin) and open pull requests to allthingslinux/tux

For step-by-step walkthroughs, see Development Setup and First Contribution.

Prerequisites¶

• Linux development environment (WSL if on Windows)
• Git — install
• Python 3.13+ — mise or pyenv recommended. Verify with python --version.
• uv — install — curl -LsSf https://astral.sh/uv/install.sh | sh, then uv --version
• PostgreSQL — local or remote (e.g. Supabase free tier)
• Discord bot token — Discord Developer Portal or Bot Token Configuration
• A Discord server with the bot added
• (Optional) Docker & Docker Compose v2 — install

Development Setup¶

1. Clone the main repo or your fork (and add upstream for forks; see above).

2. Install and hooks:

# Optional: pin Python 3.13.x for the project
uv python pin 3.13.5

uv sync
uv run pre-commit install

1. Config:

uv run config generate
cp .env.example .env
cp config/config.json.example config/config.json

Edit .env with at least:

• BOT_TOKEN

• Database — choose one:

  Option 1: Individual PostgreSQL variables (recommended)

  Bash

  POSTGRES_HOST=localhost
  POSTGRES_PORT=5432
  POSTGRES_DB=tuxdb
  POSTGRES_USER=tuxuser
  POSTGRES_PASSWORD=your_secure_password_here
  

  Option 2: Database URL override

  Bash

  DATABASE_URL=postgresql://user:password@host:port/db_name
  

Edit config/config.json: set USER_IDS.BOT_OWNER_ID to your Discord user ID (required for owner-only commands).

Find your ID. Tweak other options as needed. Regenerate examples: uv run config generate.

1. Database: If using local Docker: docker compose up -d tux-postgres (or tux-adminer for a web UI at http://localhost:8080). Then:

uv run db init
# or, to apply pending migrations only: uv run db push

Migrations create the tables; the bot also runs them on first start. Skip the Docker step if you use a remote or managed Postgres.

1. Run the bot (optional, to verify): uv run tux start --debug. The bot hot-reloads on code changes. Run $dev ct (replace $ with your prefix) to sync slash commands when you add or change them.

More detail: Development Setup and First Contribution.

Development Workflow¶

Branching¶

Tux uses trunk-based development: a single main branch that stays production-ready. Changes go through feature branches that merge into main.

Lifecycle: Create → Develop → Merge → Delete. Keep branches short-lived (about 1–3 days), merge to main frequently, and ensure main stays deployable. See Branch naming and Git best practices.

1. Create a branch¶

From main, create a branch using our branch naming conventions:

git checkout main
git pull origin main   # or: git pull upstream main (forks)
git checkout -b feat/your-feature   # or fix/, docs/, hotfix/, etc.

Keeping your branch updated: Regularly pull origin main or upstream main, then rebase your feature branch on main before opening or updating a PR. See Rebasing.

2. Implement changes¶

• Code: Numpy-style docstrings, Type | None (not Optional), and type hints. See Git best practices and Code review.
• Docs: Update docs/content/ when behavior or APIs change.
• CHANGELOG: For user-facing changes, add entries under [Unreleased] using Keep a Changelog categories: Added, Changed, Fixed, Removed, Security. Example:

## [Unreleased]

### Added
- New command for user profiles

### Fixed
- Resolved connection timeout issue

• Database: After editing models: uv run db new "short description" then uv run db dev.
• Tests: uv run test quick during development; uv run test all before opening a PR.

3. Quality checks¶

uv run dev all        # format, lint, type-check
uv run dev pre-commit # full pre-commit suite

Individual commands: uv run dev format, uv run dev lint-fix, uv run dev type-check.

Pre-commit runs: JSON/TOML validation, Ruff format/lint, import sorting, basedpyright, pydoclint, gitleaks, and conventional-commit validation.

4. Commit¶

Use Conventional Commits:

<type>[scope]: <description>

[optional body]

[optional footer]

Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert. Use lowercase, imperative mood, <120 characters, no trailing period. See Commit conventions.

Examples:

git commit -m "feat(commands): add user profile command"

# With body (for larger changes):
git commit -m "feat: implement user role system

- Add role-based permissions
- Create role assignment commands
- Update permission checks in modules"

5. Push and open a pull request¶

• Members: git push origin feat/your-feature
• Forks: git push origin feat/your-feature

On GitHub: base = allthingslinux/tux and branch = main. For forks, head = your fork and compare = your feature branch. You can use the "Compare & pull request" prompt or your fork’s "Contribute" → "Open a pull request".

PR title: [module/area] Brief description (e.g. [auth] Add OAuth2 login, [database] Optimize user query).

Link issues with Closes #123 and explain why the change is needed. Keep branches short-lived and rebase on main before opening or updating a PR.

Pull Request Process¶

1. Checks: CI must pass. Run locally: uv run test all, uv run dev all, and uv run db dev when migrations change. Ensure type hints and docstrings for public APIs, and update CHANGELOG for user-facing changes.
2. Review: Maintainers will review. PRs are discussions—be prepared to explain or adjust. Reviewers check code quality, architecture, testing, and documentation. See Code review best practices.
3. Merge: After approval and green CI, the PR is merged and the branch is removed. Changelog versioning and GitHub releases are handled by maintainers; when a version tag is pushed (e.g. v0.2.0), the changelog is bumped and a release is created.

Key resources¶

Troubleshooting¶

• Pre-commit / lint / type errors: uv run dev format, uv run dev lint-fix, uv run dev type-check
• Merge conflicts: git merge --abort to cancel; or resolve, then git add and git commit (or git mergetool). Prefer rebasing on main when possible; see Rebasing.
• Lost commits: git reflog, then git checkout <commit-hash> to restore.
• Stashing work in progress: git stash push -m "wip: short description" and git stash pop.
• Undoing changes: uncommitted file git checkout -- <file>; undo last commit but keep changes git reset --soft HEAD~1; undo last commit and discard git reset --hard HEAD~1.

Getting help¶

• Tux documentation
• Issues
• Discord — ask in a development channel

Code of Conduct and License¶

• Code of Conduct — be respectful, constructive, and inclusive.
• License (GPL-3.0) — by contributing, you agree your contributions are licensed under the same terms.