-
- 
+
+ 
@@ -39,10 +39,14 @@
## Table of Contents
+- [Table of Contents](#table-of-contents)
- [About](#about)
- [Tech Stack](#tech-stack)
- [Bot Features](#bot-features)
- [Installation and Development](#installation-and-development)
+ - [Prerequisites](#prerequisites)
+ - [Setup \& Workflow](#setup--workflow)
+ - [Quick Commands](#quick-commands)
- [License](#license)
- [Metrics](#metrics)
- [Contributors](#contributors)
@@ -56,12 +60,12 @@ It is designed to provide a variety of features to the server, including moderat
## Tech Stack
- Python 3.13+ alongside the `discord.py` library
-- Poetry for dependency management
+- Uv for dependency management
- Docker and Docker Compose for optional containerized environments
- Strict typing with `basedpyright` and type hints
-- Type safe ORM using `prisma`
+- Type safe ORM using `SQLModel` with `SQLAlchemy`
- Linting and formatting via `ruff`
-- Custom CLI via `click` and `poetry` scripts
+- Custom CLI via `typer` and `uv` scripts
- Rich logging with `loguru`
- Exception handling with `sentry-sdk`
- Request handling with `httpx`
@@ -77,16 +81,16 @@ It is designed to provide a variety of features to the server, including moderat
- Robust error handling
- Activity rotation
- Custom help command
-- Configuration system (`config/settings.yml.example`)
+- Configuration system (environment variables + `.env` file)
- Dynamic role-based (access level) permission system
-- Basic extensions system (see [extensions](tux/extensions/README.md))
+- Plugin system (see [plugins](src/tux/plugins/README.md))
## Installation and Development
### Prerequisites
- Python 3.13+
-- [Poetry](https://python-poetry.org/docs/)
+- [Uv](https://docs.astral.sh/uv/)
- A PostgreSQL database (e.g. via [Supabase](https://supabase.io/) or local installation)
- Optional: [Docker](https://docs.docker.com/get-docker/) & [Docker Compose](https://docs.docker.com/compose/install/)
@@ -94,23 +98,72 @@ It is designed to provide a variety of features to the server, including moderat
1. **Clone the repository:**
- ```bash
- git clone https://github.com/allthingslinux/tux && cd tux
- ```
+ ```bash
+ git clone https://github.com/allthingslinux/tux.git
+ cd tux
+ ```
-2. **Follow the Developer Guide:**
+2. **Install dependencies:**
- For detailed instructions on setting up:
- - your environment (local or Docker)
- - installing dependencies
- - configuring `.env` and `settings.yml`
- - managing the database
- - running the bot
- - using hot-reloading
- - linting/formatting
- - understanding the `tux` CLI commands
+ ```bash
+ uv sync
+ ```
- ### Please refer to the **[DEVELOPER.md](DEVELOPER.md)** guide for more information
+3. **Configure your environment:**
+
+ ```bash
+ cp env.example .env
+ # Edit .env with your bot tokens and database URLs
+ ```
+
+4. **Start the bot:**
+
+ ```bash
+ # Start the bot (auto-detects environment, defaults to development)
+ uv run tux start
+
+ # Start with debug mode
+ uv run tux start --debug
+ ```
+
+### Quick Commands
+
+```bash
+# Development
+uv run tux start # Start bot in development mode
+uv run tux start --debug # Start bot with debug mode
+uv run dev lint # Check code quality with Ruff
+uv run dev format # Format code with Ruff
+uv run dev type-check # Check types with basedpyright
+uv run dev pre-commit # Run pre-commit checks
+uv run dev all # Run all development checks
+
+# Testing
+uv run test run # Run tests with coverage
+uv run test quick # Run tests without coverage (faster)
+uv run test html # Run tests and generate HTML report
+uv run test coverage # Generate coverage reports
+
+# Database
+uv run db migrate-dev # Create and apply migrations for development
+uv run db migrate-push # Push pending migrations to database
+uv run db migrate-generate "message" # Generate a new migration
+uv run db health # Check database health
+
+# Docker
+uv run docker up # Start Docker services
+uv run docker down # Stop Docker services
+uv run docker build # Build Docker images
+uv run docker logs # Show Docker service logs
+uv run docker ps # List running containers
+uv run docker shell # Open shell in container
+```
+
+**For detailed setup instructions, see [SETUP.md](SETUP.md)**
+
+**For developer information, see [DEVELOPER.md](DEVELOPER.md)**
+
+**For configuration documentation, see [CONFIG.md](CONFIG.md)**
## License
diff --git a/VERSIONING.md b/VERSIONING.md
index ed9a00587..79ce25337 100644
--- a/VERSIONING.md
+++ b/VERSIONING.md
@@ -10,11 +10,28 @@ We follow the [Semantic Versioning (SemVer)](https://semver.org/) specification
- **MINOR**: Incremented for new, backward-compatible functionality.
- **PATCH**: Incremented for backward-compatible bug fixes.
-Release candidates can be denoted with suffixes (e.g., `1.0.0-rc1`).
+Release candidates can be denoted with suffixes (e.g., `1.0.0-rc.1`).
+
+## Unified Version System
+
+The Tux project uses a **unified version system** (`src/tux/shared/version.py`) that provides a single source of truth for all version-related functionality. This system is designed to be:
+
+- **DRY (Don't Repeat Yourself)**: All version logic is centralized in one module
+- **Seamless**: Works consistently across all environments (development, Docker, CI/CD)
+- **Professional**: Robust error handling, caching, and type safety
+- **Testable**: Clean, focused tests without complex mocking
+
+### Key Features
+
+- **Version Detection**: Automatic detection from multiple sources with clear priority
+- **Semantic Versioning**: Full semver validation and comparison support
+- **Caching**: Version is detected once and cached for performance
+- **Build Information**: Comprehensive build metadata including git SHA and Python version
+- **Error Handling**: Graceful fallbacks ensure the application always starts
## Version Detection
-The application version is determined dynamically at runtime. The `tux/__init__.py` module contains a robust detection mechanism that checks multiple sources in a specific order of priority. This ensures that the version is always available, regardless of the environment.
+The application version is determined dynamically at runtime using the unified version system. The `tux/__init__.py` module imports from `tux.shared.version` and exposes the detected version as `__version__`.
The `version` field in `pyproject.toml` is intentionally set to a static placeholder (`0.0.0`) because the true version is resolved dynamically.
@@ -23,32 +40,59 @@ The `version` field in `pyproject.toml` is intentionally set to a static placeho
The version is sourced by trying the following methods in order, stopping at the first success:
1. **`TUX_VERSION` Environment Variable**:
- - **Usage**: A runtime override.
+ - **Usage**: A runtime override for testing, deployment, or CI/CD scenarios.
- **Example**: `TUX_VERSION=1.2.3-custom tux --dev start`
- **Priority**: Highest. If set, this value is always used.
+ - **Use Cases**:
+ - Testing with specific versions
+ - Production deployments with custom versioning
+ - CI/CD pipelines that need to override detected versions
2. **`VERSION` File**:
- - **Usage**: The primary versioning method for Docker images. This file is generated during the Docker build process.
- - **Location**: Project root (`/app/VERSION` inside the container).
+ - **Usage**: The primary versioning method for Docker images and production deployments.
+ - **Location**: Project root (`/app/VERSION` inside containers).
+ - **Creation**: Generated during Docker build process or manually created for releases.
+ - **Use Cases**:
+ - Docker containers where git history may not be available
+ - Release builds where exact version control is required
+ - Environments where git operations are restricted
3. **Git Tags (`git describe`)**:
- **Usage**: The standard for development environments where the Git history is available.
- - **Format**: It produces version strings like:
+ - **Format**: Produces version strings like:
- `1.2.3`: For a commit that is tagged directly.
- `1.2.3-10-gabc1234`: For a commit that is 10 commits ahead of the `v1.2.3` tag.
- - `1.2.3-10-gabc1234-dirty`: If there are uncommitted changes.
+ - `1.2.3-10-gabc1234-dirty`: If there are uncommitted changes (cleaned for semver compatibility).
- **Note**: The leading `v` from tags (e.g., `v1.2.3`) is automatically removed.
+ - **Use Cases**:
+ - Development environments with full git history
+ - Local testing and development
+ - CI/CD environments with git access
-4. **Package Metadata (`importlib.metadata`)**:
- - **Usage**: For when Tux is installed as a package from PyPI or a wheel file.
- - **Mechanism**: Reads the version from the installed package's metadata.
-
-5. **Fallback to `"dev"`**:
+4. **Fallback to `"dev"`**:
- **Usage**: A final fallback if all other methods fail, ensuring the application can always start.
+ - **Use Cases**:
+ - Environments without git access
+ - Missing VERSION files
+ - Fallback when all detection methods fail
+
+### Version System API
+
+The unified version system provides several utility functions:
+
+```python
+from tux.shared.version import (
+ get_version, # Get current version
+ is_semantic_version, # Check if version is valid semver
+ compare_versions, # Compare two semantic versions
+ get_version_info, # Get detailed version components
+ get_build_info, # Get build metadata
+)
+```
## Release Cycle and Git Tagging
-The release process is centered around Git tags.
+The release process is centered around Git tags and follows semantic versioning principles.
1. **Create a Release**: To create a new version, create and push an annotated Git tag:
@@ -60,32 +104,122 @@ The release process is centered around Git tags.
2. **Development Version**: Between releases, any new commits will result in a development version string (e.g., `1.2.3-5-g567def8`), indicating progress since the last tag.
+3. **Pre-release Versions**: Use proper semver pre-release identifiers:
+
+ ```sh
+ # Release candidates
+ git tag -a v1.2.3-rc.1 -m "Release candidate v1.2.3-rc.1"
+
+ # Beta versions
+ git tag -a v1.2.3-beta.1 -m "Beta v1.2.3-beta.1"
+
+ # Alpha versions
+ git tag -a v1.2.3-alpha.1 -m "Alpha v1.2.3-alpha.1"
+ ```
+
## Docker Image Tagging
-Our Docker build process is designed to bake the version directly into the image, ensuring traceability.
+Our Docker build process is designed to bake the version directly into the image, ensuring traceability and consistency with the unified version system.
-- **Build Process**: The `Dockerfile` uses a build argument (`VERSION`) to create a `VERSION` file inside the image. This file becomes the source of truth for the version within the container.
+### Build Process
-- **Building an Image**: To build a versioned image, pass the `VERSION` argument, preferably derived from `git describe`:
+The `Dockerfile` uses build arguments to create a `VERSION` file inside the image:
- ```sh
- # Recommended command to build a production image
- docker build \
- --build-arg VERSION=$(git describe --tags --always --dirty | sed 's/^v//') \
- --target production \
- -t your-registry/tux:latest .
- ```
+```dockerfile
+ARG VERSION=""
+ARG GIT_SHA=""
+ARG BUILD_DATE=""
- You can also tag the image with the specific version:
+# Generate version file using build args with fallback
+RUN set -eux; \
+ if [ -n "$VERSION" ]; then \
+ echo "$VERSION" > /app/VERSION; \
+ else \
+ echo "dev" > /app/VERSION; \
+ fi
+```
- ```sh
- # Tag with the specific version for better tracking
- VERSION_TAG=$(git describe --tags --always --dirty | sed 's/^v//')
- docker build \
- --build-arg VERSION=$VERSION_TAG \
- --target production \
- -t your-registry/tux:$VERSION_TAG \
- -t your-registry/tux:latest .
- ```
+### Building Versioned Images
+
+To build a versioned image, pass the `VERSION` argument:
+
+```sh
+# Recommended command to build a production image
+docker build \
+ --build-arg VERSION=$(git describe --tags --always --dirty | sed 's/^v//') \
+ --target production \
+ -t your-registry/tux:latest .
+```
+
+You can also tag the image with the specific version:
+
+```sh
+# Tag with the specific version for better tracking
+VERSION_TAG=$(git describe --tags --always --dirty | sed 's/^v//')
+docker build \
+ --build-arg VERSION=$VERSION_TAG \
+ --target production \
+ -t your-registry/tux:$VERSION_TAG \
+ -t your-registry/tux:latest .
+```
+
+### GitHub Actions Integration
+
+Our GitHub Actions workflows automatically handle version generation:
+
+- **PR Builds**: Generate versions like `pr-123-abc1234`
+- **Release Builds**: Use the git tag version (e.g., `1.2.3`)
+- **Docker Builds**: Pass the generated version as build arguments
This ensures that even in a detached production environment without Git, the application reports the correct version it was built from.
+
+## Testing the Version System
+
+The version system includes comprehensive tests (`tests/unit/test_version_system.py`) that cover:
+
+- Version detection from all sources
+- Priority order validation
+- Edge cases and error handling
+- Semantic version validation
+- Build information generation
+- Integration with other components
+
+Run the tests with:
+
+```sh
+uv run pytest tests/unit/test_version_system.py -v
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Version shows as "dev"**:
+ - Check if you're in a git repository
+ - Verify the VERSION file exists and contains a valid version
+ - Ensure TUX_VERSION environment variable is not set to an empty value
+
+2. **Git describe fails**:
+ - Ensure you have at least one git tag
+ - Check git repository integrity
+ - Verify git is available in the environment
+
+3. **Docker version mismatch**:
+ - Ensure VERSION build arg is passed correctly
+ - Check that the VERSION file is created in the container
+ - Verify the Dockerfile version generation logic
+
+### Debugging
+
+You can debug version detection by checking the version system directly:
+
+```python
+from tux.shared.version import VersionManager
+
+manager = VersionManager()
+print(f"Detected version: {manager.get_version()}")
+print(f"Build info: {manager.get_build_info()}")
+print(f"Is semantic version: {manager.is_semantic_version()}")
+```
+
+This unified version system ensures consistent, reliable versioning across all environments while maintaining the flexibility needed for different deployment scenarios.
diff --git a/alembic.ini b/alembic.ini
new file mode 100644
index 000000000..f9e1eb3fa
--- /dev/null
+++ b/alembic.ini
@@ -0,0 +1,86 @@
+[alembic]
+# path to migration scripts
+script_location = src/tux/database/migrations
+
+# template used to generate migration files
+# file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
+
+# sys.path path, will be prepended to sys.path
+prepend_sys_path = src
+
+# timezone to use when rendering the date within the migration file
+# as well as the filename.
+timezone = UTC
+
+# max length of characters to apply to the
+# "slug" field
+# truncate_slug_length = 40
+
+# set to 'true' to run the environment file as part of
+# the 'revision' environment script, instead of invoking
+# the migration class directly
+# revision_environment = false
+
+# set to 'true' to allow .pyc and .pyo files without
+# a source .py file to be detected as revisions in the
+# versions/ directory
+# sourceless = false
+
+# version path separator; defaults to os.sep
+# version_path_separator = os # Use 'os' if using os.sep
+
+# the output encoding used when revision files
+# are written from script.py.mako
+# output_encoding = utf-8
+
+# This setting is used by pytest-alembic to locate migration scripts
+version_locations = src/tux/database/migrations/versions
+
+# Database URL - will be overridden by env.py based on environment
+sqlalchemy.url = postgresql://placeholder
+
+[post_write_hooks]
+# post_write_hooks defines scripts or Python functions that are run
+# on newly generated revision scripts. See the documentation for further
+# detail and examples
+
+# format using "black" - uses the console_scripts entry point defined in setup.cfg
+# hooks = black
+# black.type = console_scripts
+# black.entrypoint = black
+# black.options = -l 120
+
+# Logging configuration
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S
diff --git a/codecov.yml b/codecov.yml
new file mode 100644
index 000000000..85eb68324
--- /dev/null
+++ b/codecov.yml
@@ -0,0 +1,123 @@
+---
+# ==============================================================================
+# TUX DISCORD BOT - MODERN CODECOV CONFIGURATION
+# ==============================================================================
+#
+# This configuration follows current Codecov best practices and aligns with
+# your current test organization (unit vs integration tests).
+#
+# DOCUMENTATION: https://docs.codecov.com/docs/codecov-yaml
+# ==============================================================================
+# ==============================================================================
+# CODECOV BEHAVIOR SETTINGS
+# ==============================================================================
+codecov:
+ require_ci_to_pass: true
+ # yamllint disable-line rule:truthy
+ max_report_age: false
+ disable_default_path_fixes: false
+# ==============================================================================
+# COVERAGE REQUIREMENTS
+# ==============================================================================
+coverage:
+ precision: 2
+ round: down
+ range: 70...100
+ status:
+ project:
+ # Overall project coverage - progressive improvement
+ default:
+ target: auto
+ threshold: 1%
+ informational: true # Don't block PRs while building up test suite
+
+ # Critical components with higher standards
+ database:
+ target: 85%
+ threshold: 2%
+ informational: true
+ paths: [src/tux/database/]
+ core:
+ target: 80%
+ threshold: 2%
+ informational: true
+ paths: [src/tux/core/, src/tux/main.py, src/tux/help.py]
+ patch:
+ # New code coverage requirements
+ default:
+ target: 80%
+ threshold: 5%
+ informational: true
+ only_pulls: true
+# ==============================================================================
+# TEST FLAG DEFINITIONS
+# ==============================================================================
+# These align with your pytest markers and test organization
+flags:
+ unit:
+ paths: [src/tux/]
+ carryforward: true
+ integration:
+ paths: [src/tux/]
+ carryforward: true
+ e2e:
+ paths: [src/tux/]
+ carryforward: true
+# ==============================================================================
+# FILE IGNORING
+# ==============================================================================
+ignore:
+ # Test files and development artifacts
+ - tests/
+ - conftest.py
+ - .pytest_cache/
+ - .ruff_cache/
+ - htmlcov/
+
+ # Build and environment files
+ - .venv/
+ - typings/
+ - __pycache__/
+
+ # Project management files
+ - docs/
+ - scripts/
+ - assets/
+ - logs/
+ - '*.md'
+ - '*.toml'
+ - '*.lock'
+ - '*.nix'
+ - flake.*
+ - shell.nix
+
+ # Generated files
+ - prisma/
+# ==============================================================================
+# PARSER CONFIGURATION
+# ==============================================================================
+parsers:
+ v1:
+ include_full_missed_files: true
+# ==============================================================================
+# COMMENT CONFIGURATION
+# ==============================================================================
+comment:
+ layout: condensed_header, diff, flags, components, condensed_files, condensed_footer
+ behavior: default
+ require_changes: true
+ require_base: false
+ require_head: true
+ after_n_builds: 1
+ show_carryforward_flags: true
+# ==============================================================================
+# GITHUB INTEGRATION
+# ==============================================================================
+# Enhanced integration with GitHub's pull request interface
+github_checks:
+ annotations: true # Show line-by-line coverage in PR file diffs
+# ==============================================================================
+# PATH NORMALIZATION
+# ==============================================================================
+# Fix coverage.py path mapping for src/tux structure
+fixes: [.*/src/tux/::src/tux/, src/tux/::src/tux/]
diff --git a/config/settings.yml.example b/config/settings.yml.example
deleted file mode 100644
index 5eed2e360..000000000
--- a/config/settings.yml.example
+++ /dev/null
@@ -1,124 +0,0 @@
-# This is a example configuration file for Tux
-# Change the values to your liking and rename the file to settings.yml
-
-BOT_INFO:
- PROD_PREFIX: "$"
- DEV_PREFIX: "~" # You can enable dev mode in .env
- BOT_NAME: "Tux" # This may not apply everywhere, WIP (Best to keep it as Tux for now). Help command will be changed to be less Tux-specific if you change this.
- HIDE_BOT_OWNER: false # Hide bot owner and sysadmin from help command
- # Available substitutions:
- # {member_count} - total member count of all guilds
- # {guild_count} - total guild count
- # {bot_name} - bot name
- # {bot_version} - bot version
- # {prefix} - bot prefix
- ACTIVITIES: |
- [
- {"type": "watching", "name": "{member_count} members"},
- {"type": "listening", "name": "{guild_count} guilds"},
- {"type": "playing", "name": "{bot_name} {bot_version}"},
- {"type": "watching", "name": "All Things Linux"},
- {"type": "playing", "name": "with fire"},
- {"type": "watching", "name": "linux tech tips"},
- {"type": "listening", "name": "mpd"},
- {"type": "watching", "name": "a vast field of grain"},
- {"type": "playing", "name": "i am calling about your car's extended warranty"},
- {"type": "playing", "name": "SuperTuxKart"},
- {"type": "playing", "name": "SuperTux 2"},
- {"type": "watching", "name": "Gentoo compile..."},
- {"type": "watching", "name": "Brodie Robertson"},
- {"type": "listening", "name": "Terry Davis on YouTube"},
- {"type": "playing", "name": "with Puffy"},
- {"type": "watching", "name": "the stars"},
- {"type": "watching", "name": "VLC"},
- {"type": "streaming", "name": "SuperTuxKart", "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}
- ]
-
-# This allows sysadmins to use the eval and jsk commands which can execute arbitrary code.
-# Do enable if:
-# - Tux is dockerized
-# - You trust your sysadmins with anything that the docker container can do (e.g if they already can access the host system)
-# - You are a small server
-# DO NOT ENABLE IF:
-# - Tux is not dockerized and you do not trust your sysadmins with the host system
-# - You are a large server and Tux has full permissions
-# - You do not trust your sysadmins with anything that the docker container can do
-# - IF YOU ARE A MULTIPLE SERVER INSTANCE, DO NOT ENABLE IT FOR THE LOVE OF GOD
-# If you are not sure, do not enable this.
-ALLOW_SYSADMINS_EVAL: false
-
-USER_IDS:
- # These have access to all permissions in all servers, except for $eval and $jsk commands (unless set to true).
- # Only give these to people you trust with the bot and who are able to handle the responsibilities that come with it.
- SYSADMINS:
- - 123456789012345679
- - 123456789012345679
-
- # This should be the person who owns the bot and nobody else unless you ABSOLUTELY know what you are doing.
- # This person has access to all permissions in all servers, including $eval and $jsk commands.
- BOT_OWNER: 123456789012345679
-
-# This adds a temporary voice channel feature to the bot, you can join the channel to create a channel called /tmp/