Contributing Guide

ARQERA welcomes contributions from the community. This guide explains how to contribute code, documentation, and ideas.

Ways to Contribute

Contribution	Skill Level	Impact
Report bugs	Any	High — helps everyone
Improve docs	Any	High — makes ARQERA accessible
Fix typos	Beginner	Quick wins
Add tests	Intermediate	Improves reliability
Fix bugs	Intermediate	Direct user impact
Add features	Advanced	Shapes the product

---

Before You Start

Code of Conduct

Be respectful. Be constructive. Be inclusive.

• Treat everyone with respect
• Focus on the issue, not the person
• Assume good intentions
• Ask questions if unsure

Contributor License Agreement

For code contributions, you'll need to sign our CLA. This is a one-time process that ensures we can use your contribution.

---

Reporting Bugs

Found a bug? Help us fix it.

Check First

1. Search existing issues — it might already be reported
2. Try the latest version — it might already be fixed

Create an Issue

If it's new, create an issue with:

1. Title: Clear, concise description
2. Environment: OS, browser, ARQERA version
3. Steps to reproduce: Exactly what you did
4. Expected behavior: What should happen
5. Actual behavior: What actually happens
6. Screenshots/logs: If helpful

Good example:

Title: API returns 500 when context contains unicode

Environment: macOS 14.2, Chrome 120, ARQERA API v1.2.3

Steps:

1. Call POST /v1/governance/evaluate
2. Include emoji in context: {"message": "Hello 👋"}
3. Observe 500 response

Expected: 200 with verdict Actual: 500 Internal Server Error

Logs: [attached]

---

Suggesting Features

Have an idea? We want to hear it.

Check First

1. Search existing issues — someone might have suggested it
2. Check the roadmap — it might already be planned

Create a Feature Request

Create an issue with:

1. Title: "Feature: [your feature]"
2. Problem: What problem does this solve?
3. Solution: How would it work?
4. Alternatives: Other ways to solve this?
5. Use case: Who benefits and how?

---

Contributing Code

Setup

1. Fork the repository

   gh repo fork Arqera-IO/ARQERA

2. Clone your fork

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

3. Install dependencies

   # Backend (Python)
   cd backend
   python -m venv venv
   source venv/bin/activate
   pip install -e ".[dev]"
   
   # Frontend (TypeScript)
   cd ../frontend
   pnpm install

4. Set up pre-commit hooks

   pre-commit install

Development Workflow

1. Create a branch

   git checkout -b feat/your-feature
   # or
   git checkout -b fix/your-bugfix

2. Make changes

   • Write code
   • Add tests
   • Update docs

3. Run tests

   # Backend
   cd backend
   pytest tests/ -v
   
   # Frontend
   cd frontend
   pnpm test
   pnpm lint

4. Run the gate

   bash scripts/fast-gate.sh

5. Commit

   git add .
   git commit -m "feat: add support for X"

6. Push and create PR

   git push origin feat/your-feature
   gh pr create

Commit Messages

Follow Conventional Commits:

Prefix	Use for
feat:	New features
fix:	Bug fixes
docs:	Documentation
test:	Tests
refactor:	Code restructuring
chore:	Maintenance

Examples:

• feat: add webhook support for approvals
• fix: handle unicode in context payload
• docs: add Python SDK examples

Pull Request Guidelines

Your PR should:

• Have a clear title and description
• Reference any related issues
• Include tests for new functionality
• Pass all CI checks
• Have up-to-date documentation
• Not break existing tests

PR template:

## Summary
Brief description of changes.

## Related Issues
Fixes #123

## Changes
- Added X
- Fixed Y
- Updated Z

## Testing
How to test these changes.

## Screenshots
If UI changes, include before/after.

Code Review

All PRs require review before merging. Reviewers look for:

• Correctness — Does it work?
• Tests — Is it tested?
• Style — Does it follow conventions?
• Security — Are there vulnerabilities?
• Performance — Is it efficient?

Address feedback promptly. Ask questions if unclear.

---

Contributing Documentation

Where Docs Live

Location	Content
docs-site/docs/	Public documentation
README.md	Repository overview
Code comments	Inline explanations
docs/	Internal operational docs

Documentation Standards

1. Use plain language — No jargon
2. Be concise — Say more with less
3. Include examples — Show, don't just tell
4. Test code samples — Make sure they work
5. Use proper formatting — Markdown best practices

Building Docs Locally

cd docs-site
pnpm install
pnpm start

Docs will be available at http://localhost:3000.

Submitting Doc Changes

Same process as code:

1. Fork
2. Branch
3. Edit
4. PR

---

Project Structure

ARQERA/
├── backend/           # Python FastAPI backend
│   ├── app/
│   │   ├── api/       # API routes
│   │   ├── models/    # Database models
│   │   └── services/  # Business logic
│   └── tests/         # Backend tests
├── frontend/          # Next.js frontend
│   ├── app/           # Pages (App Router)
│   ├── components/    # React components
│   └── lib/           # Utilities
├── docs-site/         # Public documentation
├── docs/              # Internal docs
└── scripts/           # Development scripts

Key Files

File	Purpose
backend/app/services/governance_service.py	Core evaluation logic
backend/app/services/evidence_service.py	Evidence chain
frontend/hooks/useGlobalSearch.ts	Command palette search
scripts/fast-gate.sh	Pre-commit validation

---

Getting Help

Questions

• Check documentation first
• Search existing issues
• Ask in discussions

Stuck on a PR?

• Ask for help in the PR comments
• Tag a maintainer
• Join our Discord

Community

• GitHub Discussions: Long-form questions
• Discord: Real-time chat
• Twitter: @arqera_io

---

Recognition

Contributors are recognized:

• In release notes
• On our contributors page
• With commit co-authorship
• Through community spotlight

Significant contributors may be invited to:

• Beta testing
• Design reviews
• Advisory roles

---

What We're Looking For

High Priority

• Test coverage improvements
• Documentation for new features
• Performance optimizations
• Accessibility improvements
• Internationalization

Good First Issues

Look for issues labeled good first issue:

• Good first issues

These are specifically chosen for new contributors.

---

License

ARQERA is source-available. By contributing, you agree that your contributions will be licensed under the same terms.

---

Thank You

Every contribution matters. Whether you're fixing a typo or adding a major feature, you're making ARQERA better for everyone.

Start Contributing →

---

Questions? contributors@arqera.io