= Contributing to STATE
:toc: left

Thank you for your interest in contributing to STATE!

== Getting Started

=== Prerequisites

* Guile Scheme 3.0+
* Git
* (Optional) Nix for reproducible builds

=== Development Setup

[source,bash]
----
# Clone the repository
git clone https://gitlab.com/your-username/STATE.git
cd STATE

# If using Nix
nix develop

# Or install Guile manually
# Debian/Ubuntu: apt install guile-3.0
# Fedora: dnf install guile30
# macOS: brew install guile
----

=== Running Tests

[source,bash]
----
just test
# Or directly:
guile -L lib -c '(use-modules (state)) (display (state-modules-loaded))'
----

== Contribution Workflow

=== Tri-Perimeter Contribution Framework (TPCF)

This project uses graduated trust levels:

==== Perimeter 3: Community (Open to All)

* Documentation improvements
* Bug reports and feature requests
* Example STATE.scm files
* Translations
* Test cases

==== Perimeter 2: Expert (Trusted Contributors)

* New query functions
* Graph visualization enhancements
* Performance optimizations
* minikanren integration improvements

==== Perimeter 1: Core (Maintainers Only)

* Schema changes to STATE.scm format
* Core module architecture
* Security-sensitive code
* Release management

=== Making Changes

. Fork the repository
. Create a feature branch: `git checkout -b feature/your-feature`
. Make your changes
. Add tests if applicable
. Run the test suite
. Commit with a clear message
. Push and open a merge request

=== Commit Messages

Use conventional commits:

----
type(scope): description

[optional body]

[optional footer]
----

Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`

Examples:

----
feat(graph): add Mermaid flowchart export

fix(history): correct velocity calculation for zero-day intervals

docs(readme): update installation instructions
----

== Code Style

=== Scheme Guidelines

* Use 2-space indentation
* Document all exported functions with docstrings
* Keep functions small and focused
* Prefer descriptive names over abbreviations

[source,scheme]
----
;; Good
(define (get-project-by-name state name)
  "Find a project by its name."
  ...)

;; Avoid
(define (gpbn s n) ...)
----

=== SPDX Headers

All source files must include:

[source,scheme]
----
;;; SPDX-License-Identifier: MPL-2.0
;;; Copyright (c) 2025 Jonathan D.A. Jewell
----

== Documentation

* Use AsciiDoc for documentation files
* Include code examples
* Keep examples runnable
* Update CHANGELOG.md for user-facing changes

== Testing

=== Adding Tests

Create test files in `tests/` directory:

[source,scheme]
----
;;; tests/test-core.scm

(use-modules (state-core))

(define (test-get-focus)
  (let* ((test-state '(state (focus (current-project . "Test"))))
         (result (get-current-focus test-state)))
    (assert (equal? result "Test"))))
----

== Questions?

* Open an issue for questions
* Check existing issues and documentation first
* Be respectful and patient

== Recognition

Contributors are recognized in:

* MAINTAINERS.md
* Release notes
* Project documentation

Thank you for helping make STATE better!
