Skip to main content

Contributing

Thank you for your interest in contributing to Forja. This guide covers the contribution workflow, from setting up your environment to submitting a pull request.

Getting Started​

  1. Fork the repository on GitHub.
  2. Clone your fork locally: 
    git clone https://github.com/YOUR-USERNAME/forja.git
    cd forja
  3. Set up the development environment by following the Prerequisites and Installation guides.
  4. Start the dev environment: 
    ./scripts/dev-start.sh

Contribution Workflow​

1. Create a Branch​

Create a feature branch from main:

git checkout main
git pull origin main
git checkout -b feature/your-feature-name

Use descriptive branch names:

  • feature/add-bookmarks -- new feature
  • fix/cors-header-missing -- bug fix
  • docs/update-api-reference -- documentation
  • refactor/simplify-auth-guard -- code improvement

2. Make Your Changes​

Follow the coding standards documented in Coding Standards:

  • Backend: cargo fmt for formatting, cargo clippy -- -D warnings for linting.
  • Admin: npm run typecheck for types, npm run lint for linting.

3. Write Tests​

  • Add unit tests for new backend logic.
  • Add integration tests if the feature involves database operations.
  • Add component tests for new admin UI features.

4. Verify Locally​

Run the full test suite before pushing:

./scripts/dev-test.sh

For backend changes that touch the database, include integration tests:

./scripts/dev-test.sh --integration

5. Pre-Submit Checklist​

Before pushing your branch, confirm all of the following:

  • ./scripts/dev-test.sh passes (full suite)
  • cd admin && npm run react-doctor:online score is 100 (if frontend files changed)
  • Documentation updated (Docusaurus + README if applicable)
  • Changelog entry added (features and non-trivial fixes)
  • All user-visible strings use i18n keys
  • New interactive elements meet WCAG 2.1 AA
  • Error paths have dedicated error codes and i18n messages
  • Tests cover happy path, permissions, validation, and at least one edge case

6. Commit Your Changes​

Write clear, descriptive commit messages:

git add -A
git commit -m "Add bookmark management endpoints"

Commit message guidelines:

  • Use the imperative mood ("Add feature" not "Added feature").
  • Keep the first line under 72 characters.
  • Add a blank line and a longer description if the change is non-trivial.

7. Push and Create a Pull Request​

git push origin feature/your-feature-name

Open a pull request on GitHub against the main branch. In the PR description:

  • Describe what the change does and why.
  • Reference any related issues (e.g., "Closes #42").
  • Note any breaking changes or migration steps.

8. Code Review​

A maintainer will review your pull request. Be prepared to:

  • Respond to feedback and make adjustments.
  • Rebase on main if the branch falls behind.
  • Squash fixup commits before merge if requested.

What Makes a Good Contribution​

Bug Fixes​

  • Include a test that reproduces the bug.
  • Explain the root cause in the PR description.

New Features​

  • Discuss the feature in an issue before starting work to confirm it aligns with the project direction.
  • Follow the existing patterns (model/DTO/handler for backend, types/service/page for admin).
  • Add API documentation via #[utoipa::path(...)] macros.
  • Update the OpenAPI spec by registering paths and schemas in openapi.rs.

Documentation​

  • Fix typos, clarify existing docs, or add missing documentation.
  • Documentation changes do not require tests.

Development Resources​

Code of Conduct​

This project follows the Contributor Covenant Code of Conduct. By participating, you agree to uphold this standard. Please report unacceptable behavior to the project maintainers.

License​

By contributing to Forja, you agree that your contributions will be licensed under the AGPL-3.0-or-later license.