45032d937b
- releases/manifest.json: Seed release manifest for update server - update.rs: Make UPDATE_MANIFEST_URL configurable via ARCHIPELAGO_UPDATE_URL env var - CONTRIBUTING.md: Comprehensive contribution guidelines covering code style, PR process, testing, security disclosure, and app submission - .github/ISSUE_TEMPLATE/: Bug report, feature request, and app submission issue templates with structured forms - .github/pull_request_template.md: PR template with checklist Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
162 lines
4.3 KiB
Markdown
162 lines
4.3 KiB
Markdown
# 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.
|