# macro-inc/macro Contributing Guidelines: A Complete Guide to Quality Contributions

> Learn the macro-inc/macro contributing guidelines. Follow our steps for quality contributions, including issue reporting, commit naming, code formatting, and licensing.

- Repository: [Macro/macro](https://github.com/macro-inc/macro)
- Tags: how-to-guide
- Published: 2026-08-15

---

**Open an issue first, follow Conventional Commits for branch and PR naming, run `just clippy` and `cargo fmt` before pushing, and ensure all contributions are licensed under AGPL‑v3.**

Contributing to the `macro-inc/macro` project requires adherence to a structured workflow designed to maintain code quality and project consistency. This guide covers the complete contribution process, from opening your first issue to submitting a properly formatted pull request, based on the project's [`CONTRIBUTING.md`](https://github.com/macro-inc/macro/blob/main/CONTRIBUTING.md) and supporting documentation.

## Open an Issue Before Writing Code

Every contribution begins with **issue-driven development**. Before writing any code, you must open a GitHub issue describing the intended change, the problem it solves, and your proposed approach. This allows maintainers to confirm the work is needed and align on implementation details.

Pull requests submitted without a linked issue may be closed without review. This policy ensures that effort is not wasted on changes that conflict with project roadmap or duplicate existing work.

## AI-Assisted Contributions Policy

The project permits the use of **AI coding tools** for assistance, with strict accountability requirements. You must fully understand every modification you submit. Unreviewed AI output submitted verbatim will be rejected.

When using AI assistance:

- Review all generated code for correctness and security
- Ensure the output aligns with project conventions
- Be prepared to explain any line of code during review

## Branch and PR Naming Conventions (Conventional Commits)

The `macro-inc/macro` repository uses **Conventional Commits** for automated changelog generation and clear history. Follow these exact formats:

### Branch Names

```

type/scope-description

```

Examples:
- `feat/chat-dev-observability`
- `fix/document-storage-race-condition`
- `docs/api-reference-updates`

### PR Titles

```

type(scope): short description

```

Examples:
- `feat(chat): add dev observability`
- `fix(storage): resolve race condition in document lock`

The merge process automatically uses your PR title as the commit message, making this format essential for proper release notes.

## PR Body Requirements

Your pull request description must be **concise and purposeful**:

- Explain **what** changed
- Explain **why** it changed
- Include a **link to the related issue**

Avoid autogenerated boilerplate, exhaustive file-by-file lists, or AI-generated summaries that don't add context. Maintainizers review dozens of PRs; clarity and brevity are valued.

## Development Environment Setup

To test changes locally, follow the instructions in [`docs/RUNNING_LOCALLY.md`](https://github.com/macro-inc/macro/blob/main/docs/RUNNING_LOCALLY.md). The project is primarily Rust-based with additional tooling managed through the `just` command runner.

Pre-push checklist from the [`CONTRIBUTING.md`](https://github.com/macro-inc/macro/blob/main/CONTRIBUTING.md):

1. **Format code**: `cargo fmt`
2. **Run linter**: `just clippy`
3. **Execute tests**: `cargo test -p <crate>` for each modified crate
4. **Refresh SQLx cache** (if migrations changed): `just prepare_db`

The `justfile` at the repository root defines these shortcuts and ensures consistent tooling across environments.

## Complete Contribution Workflow Example

```bash

# Step 1: Create an issue on GitHub, then fetch latest code

git clone https://github.com/macro-inc/macro.git
cd macro
git checkout main
git pull

# Step 2: Create properly named feature branch

git checkout -b feat/chat-dev-observability

# Step 3: Make changes, then format and lint

cargo fmt
just clippy

# Step 4: Run tests for affected crate

cargo test -p document-storage-service

# Step 5: Refresh SQLx cache if migrations modified

just prepare_db

# Step 6: Commit using Conventional Commits format

git add .
git commit -m "feat(chat): add dev observability"

# Step 7: Push and open PR with linked issue

git push origin feat/chat-dev-observability

```

## Key Contribution Files

| File | Purpose |
|------|---------|
| [`CONTRIBUTING.md`](https://github.com/macro-inc/macro/blob/main/CONTRIBUTING.md) | Complete workflow, conventions, and licensing terms |
| [`docs/STYLE_GUIDE.md`](https://github.com/macro-inc/macro/blob/main/docs/STYLE_GUIDE.md) | Coding standards and formatting rules |
| [`docs/RUNNING_LOCALLY.md`](https://github.com/macro-inc/macro/blob/main/docs/RUNNING_LOCALLY.md) | Local development environment setup |
| `justfile` | Command shortcuts for linting, testing, and database preparation |
| [`LICENSE.txt`](https://github.com/macro-inc/macro/blob/main/LICENSE.txt) | AGPL‑v3 license governing all contributions |

## Licensing Requirements

By submitting a contribution to `macro-inc/macro`, you **agree to license your work under AGPL‑v3**. This copyleft license requires that derivative works be distributed under the same terms. Review [`LICENSE.txt`](https://github.com/macro-inc/macro/blob/main/LICENSE.txt) before contributing to understand your obligations.

## Summary

- **Always open an issue first**—PRs without linked issues may be closed
- **Use Conventional Commits** for branch names (`type/scope-description`) and PR titles (`type(scope): description`)
- **Validate locally** with `cargo fmt`, `just clippy`, and `cargo test -p <crate>`
- **Refresh SQLx cache** with `just prepare_db` when modifying database code
- **Understand every line you submit**, including AI-assisted contributions
- **License your contribution under AGPL‑v3**

## Frequently Asked Questions

### What happens if I submit a PR without opening an issue first?

PRs without linked issues may be closed without review. The issue-first policy ensures maintainer alignment before effort is invested. Open a descriptive issue, wait for feedback or acknowledgment, then proceed with implementation.

### Can I use GitHub Copilot or ChatGPT to write code for this project?

Yes, AI tools are permitted, but you must fully understand and review all modifications. Verbatim submission of unreviewed AI output is grounds for rejection. Treat AI-generated code as a starting point that requires your expertise and verification.

### What is the `just` command and why is it used?

`just` is a command runner (similar to `make`) defined in the `justfile`. It provides consistent shortcuts like `just clippy` for linting and `just prepare_db` for SQLx cache management, ensuring all contributors use identical tooling regardless of local setup.

### Why does the project use AGPL‑v3 instead of a more permissive license?

AGPL‑v3 is a strong copyleft license that ensures all derivative works, including network-accessible services, remain open source. This aligns with the project's commitment to software freedom. By contributing, you accept that your work will be governed by these terms.