Contributing to Ethotechnics

Thank you for your interest in contributing! This document outlines the process for contributing to the project.

Getting Started

Fork the repository and clone it locally.
Use the project Node version (see .nvmrc for the exact 20.x release). If you use nvm, run:
```
nvm use
```
Install dependencies (clean and reproducible, matching CI):
```
bun install
```
The repository ignores node_modules/; use bun install to reinstall a clean dependency set that mirrors CI.
Start the development server:
```
bun run dev
```
Astro serves the site with hot reload at http://127.0.0.1:4321, rebuilding templates, partials, the site config, and assets as you edit. Use bun run dev:worker when you need to exercise Worker bindings locally (after bun run build so app/dist exists).

AI agents can use Agents as the landing page for philosophy, required commands, conventions, workflow checklists, and troubleshooting playbooks.

Development Workflow

flowchart TD
    Start([Start Contributing]) --> Fork[Fork Repository]
    Fork --> Clone[Clone Locally]
    Clone --> Install["nvm use (Node 20)<br/>bun install"]
    Install --> Branch["git checkout -b<br/>feature/my-feature"]

    Branch --> Edit[Make Changes]

    Edit --> ChangeType{What changed?}

    ChangeType -->|Code| Build["bun run build"]
    ChangeType -->|Content| Build
    ChangeType -->|Styles| Build

    Build --> BuildPass{Build OK?}
    BuildPass -->|No| Edit
    BuildPass -->|Yes| Tests["bun test"]

    Tests --> TestPass{Tests pass?}
    TestPass -->|No| Edit
    TestPass -->|Yes| Lint[Check Linting]

    Lint --> LintPass{Lint OK?}
    LintPass -->|No| Edit
    LintPass -->|Yes| GitStatus["git status"]

    GitStatus --> Clean{Working tree<br/>clean?}
    Clean -->|No - Generated files| Remove[Delete build artifacts]
    Clean -->|Yes| Commit
    Remove --> Commit[Commit Changes]

    Commit --> Push[Push to Fork]
    Push --> PR[Open Pull Request]
    PR --> Review[Wait for Review]

    Review --> Approved{Approved?}
    Approved -->|Changes requested| Edit
    Approved -->|Yes| Merged([Merged!])

    style Start fill:#e8f5e9
    style Merged fill:#e8f5e9
    style Build fill:#e3f2fd
    style Tests fill:#e3f2fd
    style PR fill:#fff3e0

Directory Structure

app/: Astro project (layouts, components, static assets emitted in app/dist).
app/src/content/pages/: Astro content collection entries for pages.
app/src/components/: Shared Astro components.
styles/: CSS files (Tokens, Components, Utilities).
scripts/: Build scripts and utilities.
worker/: Cloudflare Worker code.

Making Changes

Create a new branch for your feature or fix:
```
git checkout -b feature/my-feature
```
Make your changes.
Verify your changes:
- Run bun run build to ensure the Astro build passes (outputs to app/dist).
- Run bun test to run the test suite; bun run verify mirrors the full CI sequence.
- Check for linting errors (if applicable).
- See Maintenance for the full upkeep checklist and dependency runbooks.

Build output policy

The Astro build emits rendered pages, bundled assets, and sitemap.xml in app/dist.
These artifacts are generated and excluded from version control; commit the content collection entries, shared components, site config, and source CSS they come from instead.
After running bun run build or bun run verify, the working tree should remain clean—delete generated files rather than committing them if they appear.

Test output policy

Test commands (including simulator runs) should not leave behind committed artifacts such as *_test_output.txt files.
If a test writes artifacts locally, remove them or ensure they remain ignored so that git status is clean before committing.

Style Guide

CSS: Follow the BEM naming convention. Use CSS variables from tokens.css.
HTML: Use semantic HTML5 elements. Ensure accessibility (ARIA labels, alt text).
JavaScript: Use modern ES6+ syntax.

Design Principles in Practice

Use our external references as guardrails when making UI or content changes:

/rams: Favor clarity, usefulness, and restraint—remove visual noise before adding new elements.
UI Skills: Stick to accessible primitives, predictable interaction patterns, and disciplined typography/layout constraints.
Vercel Web Interface Guidelines: Keep grids, spacing, and components consistent across pages.

External reference summaries are maintained internally and are not published in the production docs.

Submitting a Pull Request

Push your branch to your fork.
Open a Pull Request against the main branch.
Fill out the PR template with details about your changes.
Wait for review!

Reporting Issues

Please use the Issue Tracker to report bugs or request features. Use the provided templates to ensure all necessary information is included.