Contributing

We welcome contributions to ProBeya. This guide explains how to get started, our development workflow, and how to submit your changes.

Getting Started

1. Fork the repository on GitHub.
2. Clone your fork locally:

   git clone https://github.com/YOUR_USERNAME/obeya.git
   cd obeya

3. Set up the development environment following the Local Setup guide.
4. Create a branch for your changes:

   git checkout -b feat/your-feature-name

Branch Naming

Use the following prefixes:

Prefix	Purpose
feat/	New features
fix/	Bug fixes
docs/	Documentation changes
refactor/	Code refactoring without behavior changes
test/	Adding or updating tests
chore/	Build system, CI, dependency updates

Commit Messages

We follow the Conventional Commits specification:

type(scope): description

[optional body]

[optional footer]

Examples:

feat(boards): add timeline view with dependency arrows
fix(auth): handle expired session tokens gracefully
docs(api): add examples to items API reference
refactor(db): extract query builders into utility module
test(forms): add integration tests for form submission

Development Workflow

1. Make your changes in your feature branch.
2. Write tests for new functionality (see Testing).
3. Run the linter and formatter:

   pnpm lint
   pnpm format

4. Run tests:

   pnpm test

5. Commit your changes following the commit message convention.
6. Push your branch to your fork:

   git push origin feat/your-feature-name

7. Open a Pull Request on the main repository.

Pull Request Guidelines

• Title should follow the same format as commit messages.
• Description should explain what the PR does and why, not just how.
• Link related issues using Closes #123 or Fixes #456 in the description.
• Include screenshots for UI changes.
• Keep PRs focused — one logical change per PR.
• Ensure CI passes — all checks must be green before merge.

Code Review

All PRs require at least one approval from a maintainer. Reviewers will look for:

• Correctness and completeness.
• Test coverage.
• Code style and consistency.
• Performance implications.
• Security considerations.

Reporting Issues

Use GitHub Issues to report bugs or request features:

• Bug reports should include: steps to reproduce, expected behavior, actual behavior, and environment details.
• Feature requests should include: use case, proposed solution, and any alternatives considered.

Code of Conduct

We are committed to providing a welcoming and inclusive experience for everyone. Please read and follow our Code of Conduct (available in the repository root) when participating in the project.

License

By contributing to ProBeya, you agree that your contributions will be licensed under the same license as the project (AGPL-3.0).