Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
141 lines (101 loc) · 6.09 KB

CONTRIBUTING.md

File metadata and controls

141 lines (101 loc) · 6.09 KB
Raw

TrinaxAI · 🤝 Contributing

GitHub stars Stable release: 1.4.0 CI status License: AGPL-3.0-or-later Supported platforms: macOS, Windows, and Linux

English · Español

Website · Documentation · Home · Changelog

First off, thank you for considering contributing to TrinaxAI!

TrinaxAI is an open-source project and we love to receive contributions from the community. There are many ways to contribute, from writing tutorials or blog posts, improving the documentation, submitting bug reports and feature requests, or writing code which can be incorporated into TrinaxAI itself.

Code of Conduct

This project follows CODE_OF_CONDUCT.md. Be respectful, direct, and constructive.

How Can I Contribute?

Reporting Bugs

Before creating a bug report:

When reporting a bug, please include:

  • Your OS and hardware specs (CPU, RAM)
  • TrinaxAI version or commit hash
  • Steps to reproduce
  • Expected vs actual behavior
  • Any error messages or logs
  • The API request_id and index-job ID when present; redact tokens, private paths, prompts, and document contents

Suggesting Features

Feature suggestions are tracked as GitHub Issues. Please describe:

  • The problem you're trying to solve
  • How you'd like TrinaxAI to solve it
  • Any alternatives you've considered

Pull Requests

  1. Fork the repo and create your branch from main
  2. Sign off every commit for DCO: git commit -s
  3. If you've added code, add tests if applicable
  4. Run the pre-release checks (see below)
  5. Open the pull request

Translations

TrinaxAI supports multiple languages. To add or improve translations:

  • Edit chat-pwa/src/i18n/translations.ts
  • Add your language following the existing pattern (ES, EN)
  • Test that all UI elements display correctly
  • Keep every other user-visible surface bilingual as well: CLI output and help in trinaxai_cli/i18n.py (English/Spanish pairs), the localized API error contract in trinaxai/errors.py (message_es/recovery_es), the PWA manifests and offline page in chat-pwa/public/, the npm launcher messages in npm-package/bin/trinaxai.js, and the installer/updater/uninstaller scripts (tr_text/T helpers)

Documentation

Documentation improvements are always welcome! The docs live in:

  • docs/README.md — documentation map and maintenance sources of truth
  • docs/ — API, CLI, configuration, architecture, installation, and developer references
  • chat-pwa/README.md — PWA runtime and development reference
  • chat-pwa/src/components/Docs.tsx (in-app documentation)
  • README.md (project overview)
  • README.es.md (Spanish version)

Every Markdown document needs a .es.md counterpart with the same headings and code blocks; python3 scripts/public_readiness.py fails when a pair is missing or has drifted apart (this includes npm-package/README.md, chat-pwa/README.md, the ADRs in docs/adr/, and the GitHub issue/PR templates). Keep English and .es.md counterparts aligned. Verify command names against trinaxai_cli/app.py, API paths against /openapi.json, PWA scripts against chat-pwa/package.json, and user-facing recovery actions against chat-pwa/src/lib/api_errors.ts and chat-pwa/src/components/chat/MessageList.tsx.

Development Setup

The npm installation is the public path for end users. The source-checkout commands below are for contributors.

See docs/DEVELOPER_GUIDE.md for full setup instructions.

Quick start:

git clone https://github.com/TrinaxCode/TrinaxAI.git
cd TrinaxAI
./install.sh                # or install.ps1 on Windows
source .venv/bin/activate
pip install -r requirements.txt

# Frontend
(cd chat-pwa && npm install && npm run dev)

# CLI (editable install)
pip install -e .
trinaxai doctor

Pre-Release Checks

Before opening a PR or pushing to main, run these:

# Python
python3 scripts/public_readiness.py
python3 -m py_compile rag_api.py config.py index.py trinaxai_cli/app.py
ruff check .

# Frontend
cd chat-pwa
npx tsc --noEmit
npm run build
npm audit --audit-level=high

# System test (requires running services)
trinaxai doctor
python3 test_system.py --verbose

Run make readiness before opening a release-oriented pull request.

Commit Style

  • Use present tense ("Add feature" not "Added feature")
  • Keep commits focused — one logical change per commit
  • Reference issues with #123 when applicable
  • Sign off with git commit -s for DCO compliance

License

By contributing, you agree that your contribution is licensed under AGPL-3.0-or-later.

Questions?

Open a GitHub Discussion or reach out on the issue tracker.

Thanks for contributing.