docs: tighten public copy, add comparison, templates, and social preview

* docs: tighten README, CONTRIBUTING, and CLA prose

* docs: add platform comparison and README FAQ

* chore: add issue and pull request templates

* chore: add repository social preview image
This commit is contained in:
TheZwiss
2026-07-07 23:39:33 +02:00
committed by GitHub
parent 95b545d8b2
commit 3513a3dde9
9 changed files with 420 additions and 129 deletions
+82
View File
@@ -0,0 +1,82 @@
name: Bug report
description: Report something that is broken or behaving incorrectly.
labels: ["bug"]
body:
- type: markdown
attributes:
value: |
Thanks for taking the time to file a bug. Please search existing issues first to avoid duplicates.
For security vulnerabilities, do not open a public issue. See SECURITY.md and report privately.
- type: textarea
id: what-happened
attributes:
label: What happened
description: A clear description of the bug and what you expected instead.
placeholder: When I do X, Y happens. I expected Z.
validations:
required: true
- type: textarea
id: repro
attributes:
label: Steps to reproduce
description: The exact steps that trigger the problem.
placeholder: |
1. Go to ...
2. Click ...
3. See ...
validations:
required: true
- type: dropdown
id: deploy-mode
attributes:
label: Deployment mode
description: How is this instance deployed?
options:
- All-in-One (bundled Caddy)
- Behind my own reverse proxy
- Behind a tunnel (Cloudflare, Tailscale)
- Local development (pnpm dev)
- Not sure
validations:
required: true
- type: dropdown
id: surface
attributes:
label: Where did it happen
description: Which client were you using?
options:
- Web browser
- Desktop app (Electron)
- Installed PWA on mobile
validations:
required: true
- type: input
id: version
attributes:
label: Backspace version
description: The version shown in the app, or the image tag / commit you deployed.
placeholder: "1.0.0"
validations:
required: true
- type: dropdown
id: subsystems
attributes:
label: Does it involve voice or federation
description: These subsystems have their own moving parts, so it helps to know up front.
multiple: true
options:
- Voice or video (LiveKit)
- Screen sharing
- Federation between instances
- None of these
- type: textarea
id: logs
attributes:
label: Relevant logs
description: Server logs (docker compose logs backspace) or browser console output, if any. This is automatically formatted as code.
render: shell
- type: input
id: environment
attributes:
label: Browser and OS
placeholder: "Firefox 128 on Ubuntu 24.04, or Chrome 126 on Windows 11"
+8
View File
@@ -0,0 +1,8 @@
blank_issues_enabled: false
contact_links:
- name: Security vulnerability
url: https://github.com/TheZwiss/backspace/security/advisories/new
about: Do not open a public issue for security problems. Report privately here.
- name: Question or setup help
url: https://github.com/TheZwiss/backspace/discussions
about: For usage questions, deployment help, and general discussion.
@@ -0,0 +1,56 @@
name: Feature request
description: Suggest a new capability or an improvement to an existing one.
labels: ["enhancement"]
body:
- type: markdown
attributes:
value: |
Open an issue before starting work on anything non-trivial, so we can agree on direction first.
Please check the README feature list and existing issues before filing.
- type: textarea
id: problem
attributes:
label: The problem
description: What are you trying to do that Backspace does not support today?
placeholder: As a space admin, I want to ... so that ...
validations:
required: true
- type: textarea
id: proposal
attributes:
label: Proposed solution
description: How you imagine it working. Rough ideas are fine.
validations:
required: true
- type: dropdown
id: area
attributes:
label: Area
description: Which part of the project does this touch?
options:
- Text chat and messaging
- Voice, video, or screen sharing
- Spaces, roles, and permissions
- Direct messages and friends
- Federation between instances
- Admin and moderation
- Desktop app
- Mobile and PWA
- Deployment and self-hosting
- Other
validations:
required: true
- type: textarea
id: alternatives
attributes:
label: Alternatives considered
description: Workarounds you have tried, or how other tools handle this.
- type: dropdown
id: federation-impact
attributes:
label: Federation compatibility
description: Would this need to work across peered instances? If unsure, leave the default.
options:
- Not sure
- Yes, it should work across federated instances
- No, it is local to a single instance
+28
View File
@@ -0,0 +1,28 @@
<!-- Thanks for contributing. Keep one logical change per pull request. -->
## What this changes
<!-- A short summary of the change and the problem it solves. Link the issue it addresses. -->
Closes #
## Type of change
- [ ] Bug fix
- [ ] New feature
- [ ] Refactor or cleanup
- [ ] Documentation
- [ ] Other
## Checklist
- [ ] `pnpm build` succeeds (shared types, server, and web all build)
- [ ] `pnpm dev` starts the server and web client without errors
- [ ] Tests pass where applicable (`pnpm test`)
- [ ] I updated the relevant `docs/systems/` spec if this changed schema, API routes, WebSocket events, the federation protocol, permissions, or the design system
- [ ] This change resolves the correct federated identity where it compares IDs, checks permissions, or talks to remote servers (no assumption of a single global user ID)
- [ ] I have read and agree to the [CLA](../CLA.md)
## Notes for reviewers
<!-- Anything that helps review: screenshots for UI, migration notes, edge cases, follow-ups. -->