Contribution Guidelines

This page outlines the internal workflow and standards for working on ZəkaHouse.

Workflow

1. Branch

Clone the repository (team members need access granted first) and create a branch without upstream tracking, so a plain git push doesn’t accidentally update main:

git switch --no-track -c feature/your-feature-name origin/main

Branch naming conventions:

• feature/ — New features or enhancements
• fix/ — Bug fixes
• docs/ — Documentation changes
• refactor/ — Code refactoring without behavior changes

2. Make Your Changes

Develop your changes locally using the development environment. Keep commits focused and atomic.

When adding or updating dependencies:

• Frontend — Use bun to manage JavaScript/TypeScript dependencies (e.g., bun add <package>).
• Backend — Use uv to manage Python dependencies (e.g., uv add <package>). Run uv sync --locked locally before pushing if you touched pyproject.toml — a lockfile that’s out of sync fails the build in CI and in production.

3. Open a Pull Request

Push your branch and open a pull request against main:

git push -u origin feature/your-feature-name

In your pull request description:

• Explain what your change does and why it is needed.
• Include screenshots or recordings for UI changes.

Code Style

Frontend (TypeScript / React)

• Use TypeScript for all new code.
• Follow existing patterns in the codebase for component structure and naming.
• Use functional components with hooks.
• Format code consistently — the project includes configuration for code formatters.

Backend (Python)

• Follow PEP 8 conventions.
• Use type hints for function parameters and return values.
• Write clear docstrings for public functions and classes.
• Keep functions focused and concise.

Testing

• Test your changes locally before opening a pull request.
• Verify that existing functionality is not broken by your changes.
• For new features, include tests where applicable.

Review Process

After opening a pull request:

1. A teammate reviews the code and may request changes.
2. Address feedback by pushing additional commits to your branch.
3. Once approved, merge into main. Merging to main triggers a production deploy, so make sure CI is green first.