PSA/docs/contributing.md

Contributing to Alga PSA

Thank you for your interest in contributing to Alga PSA! We appreciate contributions of all kinds, whether it's fixing bugs, improving documentation, suggesting new features, or helping other users.

Ways to Contribute

• Report bugs: Open an issue describing the problem and steps to reproduce it
• Suggest features: Share ideas for new functionality via GitHub issues
• Submit code: Fix bugs or implement new features via pull requests
• Improve documentation: Help make our docs clearer and more comprehensive
• Help others: Answer questions in discussions and issues

Getting Started

1. Fork the repository and clone it locally
2. Set up your development environment following the Setup Guide
3. Create a branch for your changes:

   git checkout -b feature/your-feature-name
   # or
   git checkout -b fix/issue-description
   

Development Guidelines

• Follow existing code patterns and conventions in the codebase
• See Configuration Standards for config conventions
• Write tests for new functionality and ensure existing tests pass:

  npm run test
  

NX Modules (Monorepo)

Alga PSA uses NX + npm workspaces. Shared infrastructure lives in horizontal packages (e.g. @alga-psa/core, @alga-psa/db, @alga-psa/types), while business domains live in vertical packages (e.g. @alga-psa/clients, @alga-psa/billing).

Create a New Module

Use the generator (recommended):

NX_DAEMON=false npx nx g @alga-psa/generators:alga-module --name <module-name> --type vertical --directory packages

This creates packages/<module-name>/ with src/, package.json, tsconfig.json, and project.json.

Dependency Rules

• Vertical modules may import horizontal modules (@alga-psa/* infra packages).
• Vertical modules should not import other vertical modules directly.
• Next.js routes remain under server/src/app/ but should be thin shims that import from feature packages.
• Keep exports intentional: prefer a module src/index.ts barrel and avoid deep imports unless explicitly supported.

Submitting Changes

Pull Request Process

1. Update your branch with the latest changes from main
2. Test your changes thoroughly
3. Write a clear PR description explaining:
   • What the change does
   • Why it's needed
   • Any breaking changes or considerations
4. Link related issues using keywords like "Fixes #123"

Commit Messages

Write clear, concise commit messages that explain what changed and why:

feat: add automatic time tracking for ticket views

fix: resolve billing calculation error for quarterly cycles

docs: update setup guide with new environment variables

Reporting Issues

When reporting bugs, please include:

• A clear, descriptive title
• Steps to reproduce the issue
• Expected vs actual behavior
• Your environment (OS, browser, Node version)
• Relevant logs or screenshots

Questions?

If you have questions about contributing, feel free to open a discussion on GitHub. We're here to help you get started.

---

Thank you for helping make Alga PSA better!