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.

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)

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:

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

Deploy to dev server

./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.