Contribution Guidelines

Thank you for your interest in contributing to Plus261! This guide explains how to contribute effectively and make your contributions successful.

New Contributor?

If you’re new to the project, start with the Quick Start Guide to get set up, then return here to learn the contribution process.

What You’ll Learn

This guide will help you understand:

• ✅ The complete contribution process
• ✅ How to find or create issues
• ✅ How to create and submit merge requests
• ✅ Code quality standards
• ✅ Review process expectations

Getting Started

Before contributing, make sure you’re set up:

1. Quick Start - Set up your development environment
2. Code Structure - Understand the codebase
3. Code Style - Follow coding conventions

Contribution Process

Follow these steps to contribute effectively:

Step 1: Find or Create an Issue

• ✅ Check existing issues to see if your idea is already discussed
• ✅ Create a new issue if needed
• ✅ Discuss the approach before starting work
• ✅ Wait for approval before starting on large features

Good Issues

Good issues include:

• Clear description of the problem or feature
• Steps to reproduce (for bugs)
• Expected vs actual behavior
• Environment details
• Screenshots (if applicable)

Step 2: Fork and Clone

# Fork on GitLab, then:
git clone https://gitlab.com/<your-username>/plus261.git
cd plus261
bun install   # installs Git hooks via lefthook (prepare script)

Step 3: Create a Branch

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

Branch prefixes mirror Conventional Commits types (feat/, fix/, docs/, …).

Step 4: Make Your Changes

Follow these guidelines:

• ✅ Follow Code Style
• ✅ Write tests for new features
• ✅ Update documentation
• ✅ Keep commits focused and atomic
• ✅ Use meaningful commit messages

Learn more: Development Workflow

Step 5: Test Your Changes

# Run tests
bun test

# Code quality (monorepo root)
bun --bun run check:code

# Svelte type-check (web, auth)
cd apps/web && bun --bun run check

Tests Required

All new features must include tests. Merge requests without tests will not be merged.

Step 6: Commit Your Changes

Commit messages must follow Conventional Commits. commitlint validates every commit via Lefthook (commit-msg hook).

Lefthook also runs format and lint:fix on the whole repository before each commit (pre-commit). Hooks install automatically on bun install.

Full reference: Code Style — Commit messages (types, feat! breaking changes, examples).

Step 7: Push and Create Merge Request

git push origin feat/your-feature-name

Create a Merge Request on GitLab with:

• ✅ Clear title — describe what the MR does (Conventional Commits style recommended)
• ✅ Description — explain the changes and why
• ✅ Related issue — link to related issues
• ✅ Screenshots — if UI changes
• ✅ Test results — show that tests pass
• ✅ Checklist — mark completed items
• ✅ Breaking changes — document with feat! / BREAKING CHANGE: if applicable

Step 8: Code Review

During code review:

• ✅ Address review comments promptly
• ✅ Be open to feedback
• ✅ Keep discussions constructive
• ✅ Make requested changes
• ✅ Ask questions if unclear

Contribution Standards

Code Quality

Standard	Description
Follow conventions	See Code Style
Write clean code	Readable and maintainable
Add comments	For complex logic
Handle errors	Proper error handling

Testing

Standard	Description
Write tests	See Testing Guide
Test edge cases	Cover error scenarios
Maintain coverage	Keep test coverage high

Documentation

Standard	Description
Update docs	When adding features
Add examples	Show how to use new features
Keep docs current	Update when code changes

Types of Contributions

Bug Reports

When reporting bugs, include:

• ✅ Clear description
• ✅ Steps to reproduce
• ✅ Expected vs actual behavior
• ✅ Environment details
• ✅ Screenshots (if applicable)

Feature Requests

When requesting features:

• ✅ Describe the use case
• ✅ Explain the benefit
• ✅ Suggest implementation approach
• ✅ Consider alternatives

Code Contributions

Guidelines for code contributions:

• ✅ Small changes - Easier to review
• ✅ Focused MRs - One feature per merge request
• ✅ Well tested - Include tests
• ✅ Documented - Update docs

Documentation

Documentation contributions are welcome:

• ✅ Fix typos and errors
• ✅ Improve clarity
• ✅ Add missing information
• ✅ Add examples

Review Process

What Reviewers Look For

Reviewers evaluate contributions based on:

1. Code Quality

   • Follows style guide
   • Clean and readable
   • Proper error handling

2. Functionality

   • Works as intended
   • Handles edge cases
   • No breaking changes (unless documented with feat! + BREAKING CHANGE: — see Code Style)

3. Tests

   • Adequate test coverage
   • Tests pass
   • Edge cases covered

4. Documentation

   • Updated appropriately
   • Clear and helpful
   • Examples provided

Getting Your MR Merged

To get your merge request merged:

• ✅ Address all review comments
• ✅ Keep MR up to date with main
• ✅ Ensure all tests pass
• ✅ Get required approvals
• ✅ Resolve merge conflicts

Communication

Be Respectful

• ✅ Use inclusive language
• ✅ Be constructive in feedback
• ✅ Assume good intentions
• ✅ Be patient with newcomers

Ask Questions

• ✅ Don’t hesitate to ask
• ✅ Use GitLab issues and merge request comments
• ✅ Check existing documentation
• ✅ Reach out to maintainers

Recognition

Contributors are recognized in:

• ✅ Project README
• ✅ Release notes
• ✅ Contributor list

Quick Reference

Task	Documentation
Set up environment	Quick Start
Understand codebase	Code Structure
Follow conventions	Code Style
Write tests	Testing Guide
Development workflow	Development Guide

Next Steps

Continue your contribution journey:

1. 📚 Code Style - Coding conventions
2. 🧪 Testing - Testing guidelines
3. 🛠️ Development Workflow - Development process
4. 📖 Documentation Guide - How to contribute to docs

Related Topics

• Quick Start - Get started quickly
• Code Structure - Understand the codebase
• Code Style - Follow conventions
• Development Workflow - Development process