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

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 and 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:

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:

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:

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 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 per rule CS-25.

These constraints are defined in docs/STYLE_GUIDE.md and are checked by the just check gate.

Run Checks and Tests Before Pushing

Execute the uniform CI gate locally:

just check

This command runs cargo fmt, clippy, and TypeScript compiler checks (tsc) to enforce the style rules from 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:

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 (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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}