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).
2026-08-14 04:06:46 +01:00
parent 3e7d8097ad
commit 8c35710521
9 changed files with 363 additions and 0 deletions
@@ -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.
@@ -0,0 +1 @@
+blank_issues_enabled: false
@@ -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
@@ -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.
@@ -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)
@@ -0,0 +1,5 @@
+# Outpost Code Owners
+# These users are automatically requested for review on PRs.
+# Format: path @username
+
+* @psmattas
@@ -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.
@@ -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.
@@ -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 <repo-url>
+# 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.