# How to Contribute to the Macro Inc. Project: A Complete Developer Workflow

> Learn how to contribute to the Macro Inc project. Follow our developer workflow: create an issue, fork the repo, set up PostgreSQL, follow architecture rules, pass CI, and open a Pull Request.

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

---

**To contribute to the Macro Inc. project, open a validating GitHub issue, fork the repository, bootstrap the local PostgreSQL stack, adhere to the hexagonal service architecture and style rules, pass the `just check` CI gate, and open a Pull Request that references your issue.**

The Macro repository is a large Rust-based workspace powering an all-in-one collaborative platform. Contributing to the Macro Inc. project means navigating a strictly organized monorepo split into apps, services, and crates. Before writing code, review the official [CONTRIBUTING.md](https://github.com/macro-inc/macro/blob/main/CONTRIBUTING.md) and [docs/STYLE_GUIDE.md](https://github.com/macro-inc/macro/blob/main/docs/STYLE_GUIDE.md) to align with maintainer expectations.

## Understand the Macro Repository Architecture

The codebase is divided into three top-level layers. Knowing where your change belongs prevents rework and keeps reviews focused.

### Apps Layer

The **Apps** layer contains the SolidJS web client and Tauri desktop builds under `apps/web`, plus the documentation site under `apps/docs`. If your contribution touches the user interface or frontend build pipeline, you will work in these directories.

### Services Layer

The **Services** layer houses more than 40 deployable micro-services and Lambda workers inside `services/`. Each service follows a **hexagonal pattern**: inbound adapters route to a domain core, which then delegates to outbound adapters. When you contribute a new service or modify an existing one, preserve this structure.

### Crates and Shared Packages

The **Crates** layer groups roughly 167 reusable Rust libraries under `crates/`. Shared TypeScript utilities live in `packages/`. All components rely on a single PostgreSQL database accessed via `macro_db_client` and a bidirectional graph linking emails, messages, docs, tasks, and agents.

## Set Up Your Local Development Environment

Macro requires a running PostgreSQL instance and an up-to-date SQLx cache. Skipping these steps triggers compile-time errors such as "no cached data."

### Start the PostgreSQL Stack

Run the local Docker stack to bring up Postgres:

```bash
docker compose -f docker/docker-compose.yml up -d postgres

```

### Prepare the Database and SQLx Cache

After Postgres is healthy, create the main database and update the offline query cache:

```bash
just setup_macrodb
just prepare_db

```

The `just prepare_db` command is critical because the CI gate enforces compile-time SQL checks (`CS-08`) using the `.sqlx` offline cache. If you modify any SQL, rerun `just prepare_db` before pushing.

## Follow the Contribution Workflow

The Macro maintainers enforce a linear, issue-driven workflow. Deviating from it will delay your merge.

### Open an Issue First

Create a GitHub issue describing the bug or feature. This is the first required step when you contribute to the Macro Inc. project. The maintainers only merge Pull Requests that reference an open issue, so this step is non-negotiable.

### Branch Naming with Conventional Commits

Fork the repository, then create a branch using **Conventional Commits** style. For example:

```bash
git checkout -b feat/chat-dev-observability

```

Macro uses the branch name to generate the PR title automatically: `type(scope): short description`. This convention is documented in [`CONTRIBUTING.md`](https://github.com/macro-inc/macro/blob/main/CONTRIBUTING.md) and applied across the project.

### Implement Changes by Layer

Write code in the layer that matches your change:

- Add a new service under `services/` following the hexagonal pattern.
- Add a new crate under `crates/` for reusable domain logic.
- Use the shared macros for environment variables (`macro_env_var`) and error handling (`rootcause`).
- Keep files under roughly 1000 lines per rule `CS-24`.
- Declare sub-modules in [`mod.rs`](https://github.com/macro-inc/macro/blob/main/mod.rs) per rule `CS-25`.

These constraints are defined in [`docs/STYLE_GUIDE.md`](https://github.com/macro-inc/macro/blob/main/docs/STYLE_GUIDE.md) and are checked by the `just check` gate.

### Run Checks and Tests Before Pushing

Execute the uniform CI gate locally:

```bash
just check

```

This command runs `cargo fmt`, `clippy`, and TypeScript compiler checks (`tsc`) to enforce the style rules from [`docs/STYLE_GUIDE.md`](https://github.com/macro-inc/macro/blob/main/docs/STYLE_GUIDE.md). It mirrors the pipelines defined in `.github/workflows/` that run on every Pull Request. Next, run unit tests for any crate you modified:

```bash
cargo test -p document_storage_service

```

If you changed SQL, rerun `just prepare_db` to refresh the offline cache and prevent `CS-08` violations.

## Submit and Review Your Pull Request

Push your branch and open a Pull Request on GitHub. Mirror your branch name in the PR title using the `type(scope): short description` format. In the PR body, summarize what changed, why it changed, and link to the related issue number.

Maintainers review for architectural consistency, test coverage, and adherence to the hexagonal design. Be ready to explain your changes, run additional tests on request, and iterate quickly. The project values human understanding of contributions, especially for AI-assisted patches.

## Summary

- The Macro Inc. project is a Rust-based monorepo split into `apps/`, `services/`, and `crates/` layers.
- You must open a GitHub issue before submitting any Pull Request.
- Local development requires Docker, `just setup_macrodb`, and `just prepare_db` to satisfy SQLx offline checks.
- Code must respect the hexagonal service pattern, file-size limits (`CS-24`), and module declaration rules (`CS-25`).
- The `just check` command is the mandatory CI gate that combines formatting, linting, and compile-time SQL validation.
- Branch names and PR titles must follow Conventional Commits style.

## Frequently Asked Questions

### Do I need to open an issue before submitting a PR to Macro?

Yes. The Macro maintainers only merge Pull Requests that reference an open GitHub issue. Opening an issue first validates your proposal and prevents wasted effort on changes that may conflict with the project roadmap.

### What does the `just check` command enforce?

The `just check` command runs the full local CI gate, including `cargo fmt`, `cargo clippy`, and TypeScript compiler checks (`tsc`). It also validates compile-time SQL through the SQLx offline cache (`CS-08`), ensuring that queries are verified against the current database schema before code reaches GitHub Actions.

### How do I add a new micro-service to the Macro repository?

Place the new service under `services/` and follow the existing hexagonal architecture: inbound adapters feed a domain core, which then drives outbound adapters. Keep files under ~1000 lines (`CS-24`), declare sub-modules in [`mod.rs`](https://github.com/macro-inc/macro/blob/main/mod.rs) (`CS-25`), and use the shared `macro_env_var` and `rootcause` macros for configuration and error handling.

### Can I contribute to the SolidJS web client using the same workflow?

Yes. The `apps/web` directory contains the SolidJS web client, and it shares the same contribution rules: open an issue, use a Conventional Commit branch name, pass `just check`, and submit a PR that links the issue. The CI gate includes `tsc` for TypeScript, so all frontend changes must type-check cleanly.