Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
363 lines (256 loc) · 11.6 KB

CONTRIBUTING.md

File metadata and controls

363 lines (256 loc) · 11.6 KB
Raw

Contributing to ArchiPulse

Thank you for your interest in contributing to ArchiPulse. This project is in early development and every contribution — code, documentation, extractors, bug reports, or feedback — has real impact on its direction.

Table of Contents

Code of Conduct

ArchiPulse is committed to a welcoming and respectful environment. By participating you agree to abide by our Code of Conduct.

In short: be kind, be constructive, assume good intent.

How Can I Contribute?

Reporting Bugs

Before opening a bug report:

  1. Check existing issues to avoid duplicates
  2. Make sure you are running the latest version

Use the Bug Report template and include:

  • What you did, what you expected, what happened
  • OS, Go version (go version), PostgreSQL version
  • The AOEF or AJX file involved, if relevant (anonymized if needed)
  • Any error output or logs

Suggesting Features

Before opening a feature request:

  1. Check the roadmap — it may already be planned
  2. Check Discussions — it may already be under conversation

For small improvements: open a Feature Request issue directly.

For larger proposals affecting the API, schema, or core architecture: open a Discussion first. Read docs/ARCHITECTURE.md to understand the design decisions already made — proposals that conflict with them need to address the reasoning explicitly.

Your First Code Contribution

Look for issues labeled:

Leave a comment on the issue before starting. A maintainer will assign it to you.

Contributing an Extractor

Extractors are among the most impactful contributions. An extractor you write for your organization's data sources (AWS, Azure, Jira, Confluence, ServiceNow, custom APIs) can be reused by every ArchiPulse installation.

Extractors are self-contained and have a simple contract: collect data from a source, produce normalized JSON. They know nothing about ArchiMate — that translation happens in the mapper stage.

Canonical JSON format every extractor must produce:

{
  "clave_natural": "payments-processor",
  "nombre": "payments-processor",
  "tipo_fuente": "aws-lambda",
  "descripcion": "Handles card payment processing",
  "props": {
    "arn": "arn:aws:lambda:us-east-1:123:function:payments-processor",
    "runtime": "nodejs18.x",
    "memory": 512,
    "owner": "payments-team",
    "environment": "production"
  }
}

Rules:

  • clave_natural — stable human-meaningful identifier (function name, service name). Not the technical ID (ARN, UUID).
  • nombre and tipo_fuente are required. descripcion is optional but encouraged.
  • id is generated by ArchiPulse as hash(tipo_fuente + clave_natural) — do not generate it in the extractor.
  • props is free — put whatever is useful. Technical IDs (ARNs, UUIDs) go in props.
  • The extractor must not make assumptions about ArchiMate types — that is the mapper's job.

Extractor structure:

internal/pipeline/extractor/
└── aws-lambda/
    ├── extractor.go        # Main extractor logic
    ├── extractor_test.go   # Tests with fixture data
    ├── README.md           # Source description, config, required permissions
    └── fixtures/           # Sample API responses for tests

Contributing an EAM View

EAM views are SQL queries that generate meaningful analytical views from the workspace tables. They are one of ArchiPulse's most distinctive features and a great contribution that does not require deep Go knowledge.

Each view lives in internal/viewer/views/ as a .sql file with a corresponding Go registration:

-- internal/viewer/views/capability_map.sql
-- Description: Groups business capabilities by layer and shows application coverage
SELECT
  e.name              AS capability,
  e.layer,
  COUNT(r.id)         AS application_count
FROM elements e
LEFT JOIN relationships r ON r.target_id = e.id
  AND r.type = 'Realization'
WHERE e.workspace_id = $1
  AND e.type = 'Capability'
GROUP BY e.id, e.name, e.layer
ORDER BY e.layer, e.name;

Include a README.md in the view directory explaining what it shows and when to use it.

Improving Documentation

Documentation contributions are as valuable as code:

  • Fix typos or unclear explanations
  • Add examples or clarify the Quick Start
  • Write guides for specific use cases or data sources
  • Translate documentation

Documentation lives in docs/ and README.md. No full dev environment needed — edit Markdown and open a PR.

Development Setup

Prerequisites

Steps

# Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/archipulse.git
cd archipulse

# Add upstream remote
git remote add upstream https://github.com/DisruptiveWorks/archipulse.git

# Configure environment
cp .env.example .env
# Edit .env — set DATABASE_URL

# Build the frontend
cd cmd/archipulse/ui && npm install && npm run build && cd ../../..

# Install Go dependencies
go mod download

# Run migrations
go run ./cmd/archipulse migrate

# Build
go build ./...

# Run tests
go test ./...

# Start dev server
go run ./cmd/archipulse serve

Interface available at http://localhost:8080.

Import the example model to verify everything works:

curl -X POST http://localhost:8080/api/v1/workspaces \
  -H "Content-Type: application/json" \
  -d '{"name": "test", "purpose": "sandbox"}'

curl -X POST http://localhost:8080/api/v1/workspaces/{id}/import \
  -F "file=@examples/archisurance.xml"

Project Structure

archipulse/
├── cmd/
│   └── archipulse/
│       ├── ui/           # Svelte 5 + Vite 6 frontend
│       │   └── src/      # Components, routes, lib
│       ├── embed.go      # //go:embed ui/dist
│       └── main.go
├── internal/
│   ├── parser/           # AOEF and AJX parsers
│   ├── workspace/        # Workspace manager and CRUD operations
│   ├── viewer/           # EAM view generation
│   │   └── views/        # Individual view implementations
│   └── api/              # REST API handlers
├── migrations/           # PostgreSQL migrations (one file per version)
├── examples/             # Sample ArchiMate models (ArchiSurance, etc.)
└── tests/                # Integration tests

For the full design rationale see docs/ARCHITECTURE.md. Read it before opening proposals that affect the schema, API, or core architecture.

For the database schema with an ER diagram see docs/schema.md.

Workflow

Branching

All work on feature branches. main is always in a working, deployable state.

feature/short-description     # New functionality
fix/short-description         # Bug fixes
docs/short-description        # Documentation only
refactor/short-description    # No behavior change
test/short-description        # Tests only
extractor/source-name         # New extractor (e.g. extractor/aws-lambda)
view/view-name                # New EAM view (e.g. view/capability-map)

Commits

We follow Conventional Commits.

Format: type(scope): short description

feat(parser): add XSD validation for AOEF import
feat(extractor): add AWS Lambda extractor
feat(view): add capability map SQL view
fix(api): return 409 on optimistic lock conflict
docs(contributing): add EAM view contribution guide
test(parser): add ArchiSurance model as integration fixture

Types: feat, fix, docs, test, refactor, chore, perf

Imperative mood, under 72 characters.

Pull Requests

Before opening a PR:

  • Branch is up to date with main (git fetch upstream && git rebase upstream/main)
  • All tests pass (go test ./...)
  • Code is formatted (go fmt ./...)
  • Linter passes (golangci-lint run)
  • New functionality includes tests
  • Documentation updated if behavior changed
  • For extractors: README.md included with config and required permissions
  • For EAM views: README.md included explaining what the view shows

Use the PR template. Link the issue (Closes #42). One concern per PR. Draft PRs welcome for early feedback.

Code Style

  • Format with go fmt before committing
  • Run golangci-lint run and address warnings
  • Follow Effective Go
  • Exported symbols must have documentation comments
  • Handle errors explicitly — never discard with _ without a clear reason
  • Avoid init() functions
  • Keep functions small and focused

Testing

# All tests
go test ./...

# With coverage
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

# Specific package
go test ./internal/parser/...

Conventions:

  • Unit tests next to the code they test (parser_test.go alongside parser.go)
  • Integration tests in tests/
  • Table-driven tests for multiple inputs
  • Use example models in examples/ as fixtures — do not commit large binary files
  • For extractors: fixture files with sample API responses — no real API calls in tests
  • For EAM views: fixture workspace data in SQL — assert expected row counts and values

Decision Making

ArchiPulse is currently maintained by Disruptive Works. During early development (pre-v1.0), maintainers make final decisions on architecture, API, and roadmap.

Community input via:

  • Issues — concrete, bounded changes
  • Discussions — open-ended questions and direction
  • RFCs (coming in v0.4) — significant changes to architecture or public API

As the project grows and trusted contributors emerge, governance will evolve toward shared maintainership.

Getting Help

  • Open a Discussion in the Q&A category
  • Comment on the relevant issue

Please do not use issues for general questions — issues are for bugs and concrete feature requests.

ArchiPulse is built by people who believe Enterprise Architecture should be open, accessible, and well-tooled. We are glad you are here.