From 8c35710521614386a41176a734e4fd55b7ae8072 Mon Sep 17 00:00:00 2001 From: psavarmattas Date: Fri, 14 Aug 2026 04:06:46 +0100 Subject: [PATCH] docs: add community health files and Gitea issue/PR templates CODEOWNERS, CONTRIBUTING.md, SECURITY.md, SETUP.md, and the .gitea issue/PR templates, rewritten for Outpost (they started as copies from an unrelated project's templates - stripped the cross-repo/ticket-ID conventions and the entirely different tech stack in SETUP.md, replaced with this repo's actual submodule/OutlineKit/Xcode workflow). --- .gitea/issue_template/bug_report.yaml | 43 +++++++++ .gitea/issue_template/config.yml | 1 + .gitea/issue_template/documentation.yaml | 30 ++++++ .../security_vulnerability.yaml | 46 ++++++++++ .gitea/pull_request_template.yml | 38 ++++++++ CODEOWNERS | 5 + CONTRIBUTING.md | 71 +++++++++++++++ SECURITY.md | 38 ++++++++ SETUP.md | 91 +++++++++++++++++++ 9 files changed, 363 insertions(+) create mode 100644 .gitea/issue_template/bug_report.yaml create mode 100644 .gitea/issue_template/config.yml create mode 100644 .gitea/issue_template/documentation.yaml create mode 100644 .gitea/issue_template/security_vulnerability.yaml create mode 100644 .gitea/pull_request_template.yml create mode 100644 CODEOWNERS create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md create mode 100644 SETUP.md diff --git a/.gitea/issue_template/bug_report.yaml b/.gitea/issue_template/bug_report.yaml new file mode 100644 index 0000000..69f47c1 --- /dev/null +++ b/.gitea/issue_template/bug_report.yaml @@ -0,0 +1,43 @@ +name: Bug Report +about: Report a bug in Outpost +labels: + - "type: bug" +body: + - type: markdown + attributes: + value: | + Outpost is early alpha — please check the version in About (or your build's commit) is current before filing, and mention which platform (macOS only, for now) and OS version you're on. + - type: input + id: summary + attributes: + label: Summary + placeholder: Brief description of the bug + validations: + required: true + - type: textarea + id: steps + attributes: + label: Steps to Reproduce + value: | + 1. + 2. + 3. + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected Behavior + validations: + required: true + - type: textarea + id: actual + attributes: + label: Actual Behavior + validations: + required: true + - type: textarea + id: context + attributes: + label: Additional Context + description: Logs, screenshots, macOS version, Outline server version, etc. diff --git a/.gitea/issue_template/config.yml b/.gitea/issue_template/config.yml new file mode 100644 index 0000000..3ba13e0 --- /dev/null +++ b/.gitea/issue_template/config.yml @@ -0,0 +1 @@ +blank_issues_enabled: false diff --git a/.gitea/issue_template/documentation.yaml b/.gitea/issue_template/documentation.yaml new file mode 100644 index 0000000..57aa95c --- /dev/null +++ b/.gitea/issue_template/documentation.yaml @@ -0,0 +1,30 @@ +name: Documentation +about: Report missing, incorrect, or outdated documentation +labels: + - "type: docs" +body: + - type: input + id: page + attributes: + label: Affected Page / File + placeholder: "e.g. SETUP.md, docs/ARCHITECTURE.md, CLAUDE.md" + validations: + required: true + - type: dropdown + id: type + attributes: + label: Type + options: + - Missing documentation + - Incorrect / outdated information + - Unclear or confusing + - Typo / formatting + validations: + required: true + - type: textarea + id: description + attributes: + label: Description + description: What needs to change and why? + validations: + required: true diff --git a/.gitea/issue_template/security_vulnerability.yaml b/.gitea/issue_template/security_vulnerability.yaml new file mode 100644 index 0000000..74d6319 --- /dev/null +++ b/.gitea/issue_template/security_vulnerability.yaml @@ -0,0 +1,46 @@ +name: Security Vulnerability +about: Report a security vulnerability in this repository +labels: + - "type: security" + - "priority: critical" +body: + - type: markdown + attributes: + value: | + **Please do not disclose sensitive details publicly.** If this is a critical vulnerability, + email security@psmattas.com directly instead of filing this issue — see [`SECURITY.md`](../../SECURITY.md). + - type: input + id: summary + attributes: + label: Summary + placeholder: Brief description of the vulnerability + validations: + required: true + - type: dropdown + id: severity + attributes: + label: Severity + options: + - Critical — active exploit / data exposure + - High — exploitable with moderate effort + - Medium — limited impact or requires specific conditions + - Low — informational / hardening suggestion + validations: + required: true + - type: textarea + id: description + attributes: + label: Description + description: What is the vulnerability and how can it be exploited? + validations: + required: true + - type: textarea + id: reproduction + attributes: + label: Steps to Reproduce + description: Provide enough detail for someone to verify the issue. + - type: textarea + id: remediation + attributes: + label: Suggested Remediation + description: If you have a fix in mind, describe it here. diff --git a/.gitea/pull_request_template.yml b/.gitea/pull_request_template.yml new file mode 100644 index 0000000..f3ef3db --- /dev/null +++ b/.gitea/pull_request_template.yml @@ -0,0 +1,38 @@ +name: Pull Request +about: Standard pull request template +body: + - type: input + id: ticket + attributes: + label: Related Issue + description: "Leave blank if there isn't one." + placeholder: "Resolves #" + + - type: textarea + id: summary + attributes: + label: Summary + description: "One or two sentences — what and why." + validations: + required: true + + - type: textarea + id: changes + attributes: + label: Changes + value: "-\n-" + validations: + required: true + + - type: checkboxes + id: checklist + attributes: + label: Checklist + options: + - label: Self-reviewed + required: true + - label: "`OutlineKit` tests added/updated and passing (`swift test`), if this touches the REST layer" + required: false + - label: Verified in Xcode (there's no reliable CLI build for the app target) + required: true + - label: Docs updated (if applicable) diff --git a/CODEOWNERS b/CODEOWNERS new file mode 100644 index 0000000..f21e507 --- /dev/null +++ b/CODEOWNERS @@ -0,0 +1,5 @@ +# Outpost Code Owners +# These users are automatically requested for review on PRs. +# Format: path @username + +* @psmattas diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..7bbfc34 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,71 @@ +# Contributing to Outpost + +Thank you for contributing. Please read this guide before opening issues or PRs. + +Outpost is early alpha (`0.0.x`) — expect the codebase and conventions here to shift as Phase 1 (see [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)) settles. If something in this guide is stale, flag it. + +--- + +## Branching + +Branch from `main` using `type/short-description`: + +```bash +git checkout -b feature/document-permissions +git checkout -b fix/sidebar-context-menu +``` + +--- + +## Commit Messages + +Follow the Conventional Commits standard: `type(scope): message`. + +| Type | Description | +| :--- | :--- | +| `feat` | New feature | +| `fix` | Bug fix | +| `docs` | Documentation | +| `style` | Formatting | +| `refactor` | Refactor | +| `perf` | Performance | +| `test` | Tests | +| `build` | Build system | +| `ci` | CI/CD config | +| `chore` | Maintenance | + +**Examples:** +- `feat(collections): add document right-click context menu` +- `fix(reader): correct off-main AppKit calls in save action` + +--- + +## Pull Requests + +- Link the related issue in your PR description, if any +- Keep PRs focused — one feature or fix per PR +- Self-review before requesting review +- Run the tests that apply to what you touched (see below) and confirm the app still launches and behaves correctly in Xcode + +### Testing + +- **`OutlineKit`** (the REST client package) has real unit test coverage: + ```bash + cd OutlineKit && swift test + ``` +- **The `Outpost` app target** has no meaningful CLI build path — `xcodebuild` from the command line is not a reliable way to verify it in this project's current setup. Build and run through Xcode, and manually verify the feature you changed (and anything obviously adjacent) before opening a PR. + +--- + +## Labels + +Issues and PRs use two label prefixes: + +- `type:` — what kind of change/issue this is (`type: bug`, `type: docs`, `type: security`, ...) +- `priority:` — how urgent it is (used mainly for security reports) + +--- + +## Questions + +Open an issue — this is a single-repo project, there's no separate issue tracker to route to. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..2af656c --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,38 @@ +# Security Policy + +## Reporting a Vulnerability + +If you discover a security vulnerability in Outpost, please do **not** +open a public issue. + +Report it privately to: **security@psmattas.com** + +Include: +- A description of the vulnerability +- Steps to reproduce +- Potential impact +- Any suggested fixes if available + +We will acknowledge receipt within 48 hours and aim to release a fix +within 14 days depending on severity. + +## Supported Versions + +Outpost is in early alpha (`0.0.x`) — there's no stable release line +yet. Only the most recent tagged release receives fixes; please make +sure you're on the latest alpha before reporting. + +| Version | Supported | +| :--- | :---: | +| Latest tagged release | ✅ | +| Older releases | ❌ | + +## Scope + +Outpost is a client application that talks to a self-hosted Outline +instance you control — it doesn't run any server infrastructure of its +own. Vulnerabilities in Outline itself belong to +[outline/outline](https://github.com/outline/outline), not this repo. +API tokens are stored in the system Keychain only (never `UserDefaults`, +never logged) — see [`CLAUDE.md`](CLAUDE.md) for the relevant +conventions if you're reviewing that code path. diff --git a/SETUP.md b/SETUP.md new file mode 100644 index 0000000..66922cc --- /dev/null +++ b/SETUP.md @@ -0,0 +1,91 @@ +# Outpost Setup Guide + +## Prerequisites + +- macOS with a recent Xcode (Xcode 16 or later) +- A self-hosted Outline instance (or getoutline.com) and a personal API + key — Settings → API Keys on that instance. Outpost only ever talks + to Outline's public REST/WebSocket API; it doesn't vendor or run any + part of Outline's server. + +## 1. Clone with submodules + +The vendored OpenAPI reference (`docs/reference/outline-openapi`) is a +git submodule. + +```bash +git clone --recurse-submodules +# or, if you already cloned without it: +git submodule update --init --recursive +``` + +To pull that submodule up to whatever's newest upstream: + +```bash +git submodule update --remote docs/reference/outline-openapi +``` + +## 2. Build and test `OutlineKit` + +`OutlineKit` is a standalone Swift package (the REST client layer) and +the only part of this repo with a reliable command-line build/test path. + +```bash +cd OutlineKit +swift build +swift test +``` + +## 3. Open the app in Xcode + +```bash +open Outpost.xcodeproj +``` + +- Select the **Outpost** scheme. +- In **Signing & Capabilities**, pick your own team. A free personal + Apple ID team works fine for building and running locally — it just + means the app isn't notarized, so distributed builds trigger + Gatekeeper's "unidentified developer" warning on other machines (see + `scripts/package-dmg.sh`, which ships a README explaining the bypass). +- Run. There's no way to build the app target reliably from the CLI in + this project's current setup — use Xcode. + +## 4. Sign in + +On first launch, enter your Outline instance's URL and the API key +from step 0. The token is stored in the system Keychain only. + +## 5. Packaging a release build + +After archiving in Xcode (Product → Archive → Distribute App → Copy +App), package it into a DMG: + +```bash +./scripts/package-dmg.sh /path/to/exported/Outpost.app +``` + +This also prints a Markdown changelog (grouped by commit type, since +the last git tag) for pasting into release notes. + +## Where to go next + +- [`CLAUDE.md`](CLAUDE.md) — project conventions, phased build order, what's in/out of scope right now. +- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — deeper technical rationale (API surface, the realtime collaboration transport, the CRDT engine, known risk areas). +- [`CONTRIBUTING.md`](CONTRIBUTING.md) — branching, commit conventions, PR expectations. + +## Troubleshooting + +### `swift build`/`swift test` fails in `OutlineKit` +Make sure you're running it from inside the `OutlineKit/` directory, +not the repo root — it's a separate Swift package, not part of the +Xcode project's own build. + +### Submodule directory is empty +You cloned without `--recurse-submodules`. Run +`git submodule update --init --recursive` from the repo root. + +### App builds but sign-in fails +Double-check the server URL (including `https://`) and that the API +key hasn't been revoked on the Outline instance's Settings → API Keys +page.