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

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 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. The project is primarily Rust-based with additional tooling managed through the just command runner.

Pre-push checklist from the 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

# 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	Complete workflow, conventions, and licensing terms
docs/STYLE_GUIDE.md	Coding standards and formatting rules
docs/RUNNING_LOCALLY.md	Local development environment setup
justfile	Command shortcuts for linting, testing, and database preparation
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 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.

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