Skip to content

docs: rewrite README; deployment, usage and contributing guides; credits - #1833

Merged
magic-peach merged 2 commits into
mainfrom
docs/readme-and-contributing
Nov 3, 2026
Merged

magic-peach merged 2 commits into
mainfrom
docs/readme-and-contributing

Conversation

@magic-peach

@magic-peach magic-peach commented Nov 3, 2026 •

Copy link
Copy Markdown
Collaborator

Phase 2, part 1: docs and attribution. The code part (analytics opt-out, footer credits) is a separate PR.

Supersedes #1830: the live demo link is at the top of the new README.

What changes

  • README.md, rewritten to 126 lines:
    • logo, tagline and live demo link;
    • working badges, all for reframe-oss/reframe: stars, issues, license, CI on main, Netlify status, Snyk;
    • a demo GIF placeholder, features, how it works (three sentences, linking docs/ARCHITECTURE.md) and a three-command quick start;
    • your privacy text, a contributing summary, GSSoC'26 with its logo, and "Supported by" using <picture> light/dark logos served from this repo;
    • contrib.rocks with max=500, and the license.
    • Removed: the fork badge, the duplicated Vercel sections, the old root-level "Development Tips", and the "works offline after first load" claim. There is no service worker yet; offline support is Phase 5. docs/ARCHITECTURE.md made the same claim and is corrected too.
  • docs/DEPLOYMENT.md (new): Netlify first, why COOP/COEP matter and how to check them, Cloudflare Pages, Vercel, and GitHub Pages (single-threaded only).
  • docs/USAGE.md (new): the editing flow, undo and recovery, and keyboard shortcuts as the code defines them. The old README missed Ctrl+Shift+E, I/O (set trim points from the playhead), R, 1–9 and ?. It also explains what happens when an export is slow.
  • CONTRIBUTING.md, rewritten:
    • Bun setup and the commands, including the Playwright tests;
    • claiming with /assign and the bot's rules, branch prefixes, and Conventional Commits;
    • the PR checklist (lint, typecheck, test, build, plus Playwright for export changes), the screen-recording requirement, review (a human merges), and Chromatic;
    • project rules from CLAUDE.md, dev tips (moved from the README) and GSSoC notes.
    • The useful parts of CONTRIUBUTION.md (bug reports, feature requests, branch naming) are folded in, and that file is deleted.
  • CODE_OF_CONDUCT.md was already Contributor Covenant v2.1, but its contact was [INSERT CONTACT METHOD]. TODO for you: it now shows a visible TODO and an interim route (GitHub's report-abuse form, or tag @magic-peach on an issue). Please add a private contact address. SECURITY.md also still says [maintainer email].
  • MIT LICENSE → LICENSE, so GitHub detects the license and the badge works.
  • PHASE_1_MVP.md → docs/history/; the one link to it is updated.
  • all-contributors: .all-contributorsrc (empty list) and .github/ALL_CONTRIBUTORS.md, with instructions for crediting reviewers, mentors, designers and others through the bot or the CLI. Nobody is added automatically.

Logos: please download the official files

No third-party image is hotlinked. Logos live in docs/assets/brand/.

File(s) What's there now Replace with
netlify-light.svg, netlify-dark.svg Copies of the official "Deploys by Netlify" badge that was already in public/badges/ Keep, or use the light and dark logos from Netlify's press kit: https://www.netlify.com/press/
datadog-light.png, datadog-dark.png Copies of the Datadog logo already in public/badges/ (2000×2000) The horizontal logo in purple (light) and white (dark) from Datadog's brand resources: https://www.datadoghq.com/about/resources/ , or the files from the Open Source Program welcome email
snyk-light.svg, snyk-dark.svg Placeholder (text in a dashed box) Snyk's logo, or the badge their open source program asks for, from https://snyk.io/press-kit/ or the program's welcome email
gssoc-light.svg, gssoc-dark.svg Placeholder The GSSoC 2026 logo from the GirlScript organisers' project-admin kit (https://gssoc.girlscript.tech)
chromatic-light.svg, chromatic-dark.svg Placeholder (the old README hotlinked Chromatic's logo from githubusercontent) Chromatic's logo from their brand or open source page
docs/assets/demo-placeholder.svg Placeholder A short export recording saved as docs/assets/demo.gif (under 5 MB), with the README <img> pointed at it

Keep the same file names and the README needs no changes. I kept Chromatic under "Supported by" even though your list named only Netlify, Snyk and Datadog, because it provides the visual review service; remove it if you prefer.

Stray root files: your decision

  • vercel.json: Netlify is the only host, but vercel.json still mirrors the headers and docs/DEPLOYMENT.md mentions it for forks. Options: delete it (and the Vercel row and the comments in netlify.toml and public/_headers that reference it), or keep it as an unmaintained example.
  • The file named reframe is gone: it was a phantom submodule, removed in fix: remove phantom git submodule reference at path "reframe" #1765.
  • Other root files look intentional: .snyk, .env.example, CHANGELOG.md, SECURITY.md, CLAUDE.md, and the configs.

Notes

- README: about 120 lines. Working badges for reframe-oss/reframe (stars,
  issues, license, CI on main, Netlify status, Snyk), the live demo link,
  a demo placeholder, features, how it works, quick start, privacy,
  contributing, GSSoC, "Supported by" with self-hosted light/dark logos, and
  contrib.rocks. Removes the fork badge, the duplicated Vercel sections and
  the "works offline after first load" claim (there is no service worker).
- docs/DEPLOYMENT.md (Netlify first, cross-origin isolation explained),
  docs/USAGE.md (flow, keyboard shortcuts as the code defines them, what to
  do when an export is slow).
- CONTRIBUTING.md rewritten: Bun setup, claiming with /assign, branch names,
  Conventional Commits, PR checklist (lint, typecheck, test, build), review,
  project rules, GSSoC notes. Folds in CONTRIUBUTION.md, which is removed.
- CODE_OF_CONDUCT.md: the [INSERT CONTACT METHOD] placeholder becomes a
  visible TODO with a working interim route.
- "MIT LICENSE" renamed to LICENSE (so GitHub detects it); PHASE_1_MVP.md
  moved to docs/history/.
- all-contributors config and .github/ALL_CONTRIBUTORS.md with instructions;
  nobody is added automatically.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@netlify

netlify Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for reframe-os ready!

Name Link
🔨 Latest commit c06e622
🔍 Latest deploy log https://app.netlify.com/projects/reframe-os/deploys/6aea09cca7cf2b9218583582
😎 Deploy Preview https://deploy-preview-1833--reframe-os.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@github-actions github-actions Bot added level:advanced Advanced level - 55 pts type:bug Bug fix type:docs Documentation type:feature New feature type:performance Performance type:security Security type:testing Testing labels Nov 3, 2026
@github-actions

github-actions Bot commented Nov 3, 2026

Copy link
Copy Markdown
Contributor

⚠️ PR Format Issues — @magic-peach

Please fix the following before your PR can be reviewed:

  • ⚠️ No linked issue found. Add Closes #<issue-number> to your PR description.

Push new commits after fixing — this comment will update automatically.

📖 CONTRIBUTING.md

@github-actions

github-actions Bot commented Nov 3, 2026

Copy link
Copy Markdown
Contributor

👋 Thanks for your PR, @magic-peach!

Welcome to Reframe — a browser-based video editor built for everyone 🎬

🟠 GSSoC'26 PR detected — thanks for contributing under GirlScript Summer of Code 2026!

What happens next

  1. 🤖 Automated checks — build & TypeScript typecheck will run automatically
  2. ✅ Vercel preview — a preview deployment will be created (requires maintainer authorization for fork PRs)
  3. 👀 Code review — a maintainer will review your changes
  4. 🚀 Merge — once approved, your PR will be merged!

Quick checklist

  • PR title follows Conventional Commits (e.g. feat: add dark mode)
  • Linked the issue this PR closes (e.g. Closes #123)
  • Tested the changes locally (bun run dev)
  • Build passes (bun run build)

Useful links

Happy coding! 🎉

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@magic-peach
magic-peach marked this pull request as ready for review November 3, 2026 16:32
@magic-peach
magic-peach merged commit e867004 into main Nov 3, 2026
20 of 22 checks passed
@github-actions

github-actions Bot commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

Claude encountered an error —— View job


I'll analyze this and get back to you.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

gssoc'26 GirlScript Summer of Code 2026 level:advanced Advanced level - 55 pts type:bug Bug fix type:docs Documentation type:feature New feature type:performance Performance type:security Security type:testing Testing

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant