chore: prepare repository for public launch
This commit is contained in:
Dorian
+65
-126
@@ -1,161 +1,100 @@
|
||||
# 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.
|
||||
This project is preparing for public developer contribution. The highest-value
|
||||
contributions are focused fixes, tests, app manifests, documentation
|
||||
improvements, and clear bug reports with reproducible evidence.
|
||||
|
||||
## Code of Conduct
|
||||
## Development setup
|
||||
|
||||
Be respectful. We follow the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
|
||||
|
||||
## Getting Started
|
||||
|
||||
1. Fork the repository on the project's Gitea instance
|
||||
2. Clone your fork: `git clone <your-fork-url>/archy.git`
|
||||
3. Set up the dev environment (see `docs/developer-guide.md`)
|
||||
4. Create a feature branch: `git checkout -b feature/your-feature`
|
||||
|
||||
## Development Setup
|
||||
|
||||
### Frontend (Vue.js)
|
||||
### Frontend
|
||||
|
||||
```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
|
||||
npm start
|
||||
npm run type-check
|
||||
npm test
|
||||
```
|
||||
|
||||
### Backend (Rust)
|
||||
|
||||
Build on a Linux server (Debian 13), **not** macOS:
|
||||
### Backend
|
||||
|
||||
```bash
|
||||
cargo clippy --all-targets --all-features
|
||||
cargo fmt --all
|
||||
cd core
|
||||
cargo fmt --all -- --check
|
||||
cargo clippy --all-targets --all-features -- -D warnings
|
||||
cargo test --all-features
|
||||
```
|
||||
|
||||
### Deploy to dev server
|
||||
Linux is required for host integration work involving Podman, systemd,
|
||||
networking, or image builds. Frontend development works locally with the mock
|
||||
backend.
|
||||
|
||||
## App manifests
|
||||
|
||||
App packages live under `apps/<app-id>/manifest.yml` and use the schema
|
||||
documented in [docs/app-manifest-spec.md](docs/app-manifest-spec.md). Validate
|
||||
before submitting:
|
||||
|
||||
```bash
|
||||
./scripts/deploy-to-target.sh --live
|
||||
./scripts/validate-app-manifest.sh apps/<app-id>/manifest.yml
|
||||
python3 scripts/generate-app-catalog.py
|
||||
python3 scripts/check-app-catalog-drift.py --release --strict
|
||||
```
|
||||
|
||||
## Code Style
|
||||
App submissions must:
|
||||
|
||||
### Frontend (TypeScript + Vue)
|
||||
- pin container image versions;
|
||||
- avoid hardcoded secrets;
|
||||
- use `security.no_new_privileges: true`;
|
||||
- use `security.readonly_root: true` unless the manifest explains why writable
|
||||
root is required;
|
||||
- request only necessary Linux capabilities;
|
||||
- store durable data under `/var/lib/archipelago/<app-id>/`;
|
||||
- define truthful health checks and launch interfaces for user-facing UIs.
|
||||
|
||||
- `<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
|
||||
## Code style
|
||||
|
||||
### Backend (Rust)
|
||||
- Rust: prefer `?` over `unwrap()`/`expect()` in production paths.
|
||||
- Rust: use `tracing` for structured logs.
|
||||
- TypeScript: avoid `any`; use explicit types or `unknown`.
|
||||
- Vue: prefer `<script setup lang="ts">`.
|
||||
- Keep changes scoped; do not mix drive-by refactors with behavioral changes.
|
||||
- Remove dead code rather than commenting it out.
|
||||
- Add tests for new behavior and regression tests for bug fixes.
|
||||
|
||||
- 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
|
||||
## Pull requests
|
||||
|
||||
### General
|
||||
1. Open one focused PR per behavior or documentation change.
|
||||
2. Explain what changed, why it changed, and how it was verified.
|
||||
3. Include screenshots for UI changes.
|
||||
4. Link relevant issues or docs.
|
||||
5. Keep generated catalog changes in sync with manifest changes.
|
||||
|
||||
- Functions under 50 lines, single responsibility
|
||||
- Comment WHY not WHAT
|
||||
- Remove dead code — never comment it out
|
||||
- No `TODO`/`FIXME` in commits
|
||||
Suggested commit format:
|
||||
|
||||
## Commit Format
|
||||
|
||||
```
|
||||
type: description
|
||||
```text
|
||||
feat: add backup scheduling
|
||||
fix: reject unsafe manifest volume
|
||||
docs: clarify app deployment flow
|
||||
test: cover catalog drift check
|
||||
```
|
||||
|
||||
**Types**: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`, `perf:`
|
||||
## Reporting bugs
|
||||
|
||||
Examples:
|
||||
- `feat: add backup scheduling to settings page`
|
||||
- `fix: handle WiFi connection timeout gracefully`
|
||||
- `test: add unit tests for RPC client retry logic`
|
||||
Include:
|
||||
|
||||
## Pull Request Process
|
||||
- exact version or commit;
|
||||
- host platform and architecture;
|
||||
- steps to reproduce;
|
||||
- expected and actual behavior;
|
||||
- logs from the relevant component;
|
||||
- screenshots for UI issues.
|
||||
|
||||
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
|
||||
## Security
|
||||
|
||||
### 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.
|
||||
Do not report vulnerabilities in public issues. Follow [SECURITY.md](SECURITY.md).
|
||||
|
||||
## License
|
||||
|
||||
By contributing, you agree that your contributions will be licensed under the same license as the project.
|
||||
By contributing, you agree that your contribution is licensed under the
|
||||
project's MIT License.
|
||||
|
||||
Reference in New Issue
Block a user