archy/CONTRIBUTING.md

# Contributing to Archipelago

Thank you for your interest in contributing to Archipelago! This document covers the process for contributing code, reporting bugs, and submitting apps.

## Code of Conduct

Be respectful. We follow the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).

## Getting Started

1. Fork the repository
2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/archy.git`
3. Set up the dev environment (see `docs/development-setup.md`)
4. Create a feature branch: `git checkout -b feature/your-feature`

## Development Setup

### Frontend (Vue.js)

```bash
cd neode-ui
npm install
npm start          # Dev server on :8100
npm run type-check # TypeScript validation
npm run build      # Production build
npm test           # Run tests
```

### Backend (Rust)

Build on a Linux server (Debian 12), **not** macOS:

```bash
cargo clippy --all-targets --all-features
cargo fmt --all
cargo test --all-features
```

### Deploy to dev server

```bash
./scripts/deploy-to-target.sh --live
```

## Code Style

### Frontend (TypeScript + Vue)

- `<script setup lang="ts">` — always Composition API
- TypeScript strict mode — no `any`, use `unknown` or proper types
- Global CSS classes in `src/style.css` — never inline Tailwind in components
- Pinia for state management — focused single-purpose stores
- Use `@/api/rpc-client.ts` for RPC calls

### Backend (Rust)

- No `unwrap()` or `expect()` in production code — use `?` operator
- `thiserror` for library errors, `anyhow` for application errors
- `tracing` for structured logging — never `println!`
- Run `cargo clippy` and `cargo fmt` before commits

### General

- Functions under 50 lines, single responsibility
- Comment WHY not WHAT
- Remove dead code — never comment it out
- No `TODO`/`FIXME` in commits

## Commit Format

```
type: description
```

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

Examples:
- `feat: add backup scheduling to settings page`
- `fix: handle WiFi connection timeout gracefully`
- `test: add unit tests for RPC client retry logic`

## Pull Request Process

1. Ensure your branch is up to date with `main`
2. All checks must pass: TypeScript, build, tests, clippy
3. Include a clear description of what changed and why
4. Link any related issues
5. Request review from a maintainer

### PR Checklist

- [ ] TypeScript type-check passes (`npm run type-check`)
- [ ] Frontend builds (`npm run build`)
- [ ] Tests pass (`npm test`)
- [ ] Rust clippy clean (`cargo clippy --all-targets --all-features`)
- [ ] No new compiler warnings
- [ ] Follows code style guidelines above

## Testing Requirements

- New features need tests
- Bug fixes need a regression test
- Frontend: Vitest + Vue Test Utils
- Backend: `#[test]` and `#[tokio::test]`
- Target: maintain or improve existing coverage

## Reporting Bugs

Use the **Bug Report** issue template. Include:

1. Steps to reproduce
2. Expected behavior
3. Actual behavior
4. System info (hardware, OS version, Archipelago version)
5. Screenshots if applicable
6. Relevant logs (`journalctl -u archipelago`)

## Feature Requests

Use the **Feature Request** issue template. Include:

1. Problem description
2. Proposed solution
3. Alternatives considered
4. Impact on existing users

## App Submissions

To submit an app for the Archipelago marketplace:

1. Create a manifest following `docs/app-manifest-spec.md`
2. Ensure the container image is published to a public registry
3. Test on Archipelago hardware (x86_64 and ARM64 if possible)
4. Open a PR adding the app to the curated list
5. Include: app description, icon, resource requirements, dependencies

### App Requirements

- Container must run as non-root (UID > 1000)
- `readonly_root: true` unless explicitly justified
- Drop all capabilities except those required
- `no-new-privileges: true`
- Pin specific image versions (no `latest` tag)
- No hardcoded secrets

## Security Disclosure

**Do NOT open public issues for security vulnerabilities.**

Email security concerns to the maintainers directly. Include:

1. Description of the vulnerability
2. Steps to reproduce
3. Potential impact
4. Suggested fix (if any)

We will acknowledge receipt within 48 hours and provide a timeline for a fix.

## License

By contributing, you agree that your contributions will be licensed under the same license as the project.