Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
141 lines (99 loc) · 3.94 KB

CONTRIBUTING.md

File metadata and controls

141 lines (99 loc) · 3.94 KB
Raw

Contributing to AmbientOps

Thank you for your interest in contributing to AmbientOps. This document covers the development setup, contribution workflow, and coding standards for the project. AmbientOps uses a hospital-model architecture; please familiarise yourself with the component layout in README.adoc before diving in.

’’’’’

Getting Started

# Clone the repository
git clone https://github.com/hyperpolymath/ambientops.git
cd ambientops

# Using Guix (recommended for reproducibility)
guix develop

# Or using toolbox/distrobox
toolbox create ambientops-dev
toolbox enter ambientops-dev
# Install dependencies manually

# Verify setup
just check   # or: cargo check / mix compile / etc.
just test    # Run test suite

Repository Structure

ambientops/
├── src/                 # Source code (Perimeter 1-2)
├── lib/                 # Library code (Perimeter 1-2)
├── extensions/          # Extensions (Perimeter 2)
├── plugins/             # Plugins (Perimeter 2)
├── tools/               # Tooling (Perimeter 2)
├── docs/                # Documentation (Perimeter 3)
│   ├── architecture/    # ADRs, specs (Perimeter 2)
│   └── proposals/       # RFCs (Perimeter 3)
├── examples/            # Examples (Perimeter 3)
├── spec/                # Spec tests (Perimeter 3)
├── tests/               # Test suite (Perimeter 2-3)
├── .well-known/         # Protocol files (Perimeter 1-3)
├── .github/             # GitHub config (Perimeter 1)
│   ├── CONTRIBUTING.md  # This file
│   ├── ISSUE_TEMPLATE/
│   └── workflows/
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── GOVERNANCE.md
├── LICENSE
├── MAINTAINERS.md
├── README.adoc
├── SECURITY.md
├── flake.guix            # Guix flake (Perimeter 1)
└── Justfile             # Task runner (Perimeter 1)

’’’’’

How to Contribute

Reporting Bugs

Before reporting: 1. Search existing issues 2. Check if it’s already fixed in main 3. Determine which perimeter the bug affects

When reporting:

Use the bug report template and include:

  • Clear, descriptive title

  • Environment details (OS, versions, toolchain)

  • Steps to reproduce

  • Expected vs actual behaviour

  • Logs, screenshots, or minimal reproduction

Suggesting Features

Before suggesting: 1. Check the roadmap if available 2. Search existing issues and discussions 3. Consider which perimeter the feature belongs to

When suggesting:

Use the feature request template and include:

  • Problem statement (what pain point does this solve?)

  • Proposed solution

  • Alternatives considered

  • Which perimeter this affects

Your First Contribution

Look for issues labelled:

’’’’’

Development Workflow

Branch Naming

docs/short-description       # Documentation (P3)
test/what-added              # Test additions (P3)
feat/short-description       # New features (P2)
fix/issue-number-description # Bug fixes (P2)
refactor/what-changed        # Code improvements (P2)
security/what-fixed          # Security fixes (P1-2)

Commit Messages

We follow Conventional Commits: ``` ():

[optional body]

[optional footer]