Update contribution guidelines and PR template

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,27 @@
+## What and why
+
+<!-- What does this PR change, and what problem does it solve?
+     Please write this yourself, in your own words. -->
+
+## Prior discussion
+
+<!-- Bug fix: link the issue.
+     Feature/change: link the discussion or forum thread where it got a
+     green light. If there isn't one yet, please start there first:
+     https://github.com/orgs/asciinema/discussions -->
+
+## How it was tested
+
+<!-- e.g. test suite run, manual testing steps, platforms/browsers checked -->
+
+## AI assistance
+
+<!-- If AI tools were part of your workflow, note which and to what extent
+     (e.g. "Claude Code wrote the initial patch, I reviewed and adjusted it").
+     Write "none" if not applicable. -->
+
+## Checklist
+
+- [ ] I fully understand the changes I'm proposing and can answer questions about them
+- [ ] I wrote the description above in my own words
+- [ ] The test suite passes locally

CONTRIBUTING.md

@@ -1,46 +1,133 @@
 # Contributing to asciinema
 
-First, if you're opening a GitHub issue make sure it goes to the correct
+Thank you for your interest in contributing! This document describes how
-repository:
+contributions work across the asciinema ecosystem:
 
-- [asciinema/asciinema](https://github.com/asciinema/asciinema/issues) - command-line recorder
+- [asciinema](https://github.com/asciinema/asciinema) - the CLI: terminal
-- [asciinema/asciinema-server](https://github.com/asciinema/asciinema-server/issues) - public website hosting recordings
+  session recorder, streamer and player
-- [asciinema/asciinema-player](https://github.com/asciinema/asciinema-player/issues) - player
+- [asciinema-player](https://github.com/asciinema/asciinema-player) - the web
+  player
+- [asciinema-server](https://github.com/asciinema/asciinema-server) - the
+  hosting and streaming platform
+- [agg](https://github.com/asciinema/agg) - the GIF generator
+- [avt](https://github.com/asciinema/avt) - the virtual terminal library
+- [docs](https://github.com/asciinema/asciinema.github.io) - the documentation
+  site
+
+## How asciinema is developed
+
+asciinema is a passion project, built and maintained in spare time by a very
+small team. The project follows a simple philosophy: a focused set of stable,
+robust tools that work well together and stay out of your way.
+
+Development is idea-driven rather than roadmap-driven. There is no formal
+roadmap. New functionality usually gets added once an idea has proven itself,
+often by resurfacing repeatedly in discussions and finding a shape that fits
+the rest of the project. This deliberate pace is a feature: it's what keeps
+asciinema small, dependable and easy to maintain for the years ahead.
+
+## Where things go
+
+- **Bug reports** belong in the issue tracker of the relevant repository.
+  Our issue trackers are for bug reports only.
+- **Feature ideas and change proposals** belong in the GitHub discussions
+  ["Ideas" category](https://github.com/orgs/asciinema/discussions/categories/ideas)
+  or on the [forum](https://discourse.asciinema.org/).
+- **Questions and help requests** belong on the
+  [forum](https://discourse.asciinema.org/) or in the GitHub discussions
+  ["Q&A" category](https://github.com/orgs/asciinema/discussions/categories/q-a).
+  The issue tracker is not a support channel.
+- **Security issues** should be reported privately to admin@asciinema.org.
+  Please do not describe vulnerabilities in public issues or discussions.
 
 ## Reporting bugs
 
-Open an issue in GitHub issue tracker.
+Search existing issues first, including closed ones - your bug may already be
+fixed or reported. If it's new, open an issue in the repository the bug
+belongs to and fill in the issue template completely. Reliable reproduction
+steps and environment details (OS, terminal, browser, versions) make the
+difference between a quick fix and a stalled report.
 
-Tell us what's the problem and include steps to reproduce it (reliably).
+If you're not sure whether something is a bug, or you can't reproduce it
-Including your OS/browser/terminal name and version in the report would be
+reliably, start with a discussion or forum thread instead.
-great.
 
-## Submitting patches with bug fixes
+## Proposing features and changes
 
-If you found a bug and made a patch for it:
+For anything beyond a small bug fix, please talk to us before writing code:
 
-1. Make sure all tests pass. If you add new functionality, add new tests.
+1. Start a thread in the
-1. Send us a pull request, including a description of the fix (referencing an
+   ["Ideas" discussions category](https://github.com/orgs/asciinema/discussions/categories/ideas)
-   existing issue if there's one).
+   or on the [forum](https://discourse.asciinema.org/).
+2. Describe the problem you're solving, your proposed approach, and who would
+   benefit from it.
+3. If a maintainer gives the idea a green light, a pull request is very
+   welcome. Link the thread in your PR. A green light means the idea is worth
+   exploring, not a commitment to merge a particular implementation.
 
-## Requesting new features
+Here's why we ask for this. When a change is merged, the responsibility for it
+shifts to the maintainers: from that point on we adapt it during refactorings,
+fix bugs in it, and support the people using it, for as long as the code
+lives. Every merge is a long-term commitment, so we are deliberate about which
+commitments we take on. Proposals that benefit a broad range of users and fit
+the project's focus have the best chance of being accepted.
 
-We welcome all ideas.
+Pull requests opened without prior discussion may stay unreviewed for a long
+time or be closed. Even useful, well-implemented changes may be declined when
+they don't fit the project's direction or when we can't take on their
+long-term maintenance.
 
-If you believe most asciinema users would benefit from implementing your idea
+If your change is specific to your workflow, or it's something we can't adopt
-then feel free to open a GitHub issue. However, as this is an open-source
+right now, maintaining it in your own fork is a perfectly good outcome, and
-project maintained by a small team of volunteers we simply can't implement all
+one we genuinely encourage. The licenses give you all the freedom you need,
-of them due to limited resources. Please keep that in mind.
+and we're happy when asciinema code is useful even outside the main line.
 
-## Proposing features/changes (pull requests)
+## Pull requests
 
-If you want to propose code change, either introducing a new feature or
+Bug fix PRs can be opened directly; reference the issue if there is one.
-improving an existing one, please first discuss this with asciinema team. You
+Feature PRs should follow a green-lit discussion (see above).
-can simply open a separate issue for a discussion or join #asciinema IRC
-channel on Libera.Chat.
 
-## Reporting security issues
+What we look for in a PR:
 
-If you found a security issue in asciinema please contact us at
+- Keep it focused and as small as practical. We may ask for a large change to
-admin@asciinema.org. For the benefit of all asciinema users please **do
+  be split into smaller ones.
-not** publish details of the vulnerability in a GitHub issue.
+- Match the style and conventions of the surrounding code, and run the
+  repository's formatter before submitting.
+- Make sure the test suite passes, and add tests covering new behavior.
+- Write the description yourself, in your own words: what the change does,
+  why, and how you tested it.
+
+We care about the long-term shape of the codebase, so reviews can be picky
+about naming, structure and consistency, even when a change already works.
+Sometimes we'll ask for adjustments or suggest a different implementation
+before merging. Review timelines vary with maintainer availability; your
+patience is appreciated.
+
+### In this repository
+
+- Pull requests should target the `develop` branch. The `python` branch holds
+  the legacy 2.x codebase and is not under active development.
+- Verify your changes with `cargo test`.
+
+## AI-assisted contributions
+
+It's fine to use AI coding tools when working on a contribution. A few
+expectations keep this working well for everyone:
+
+- **Disclose AI use in your PR description**: which tool, and to what extent
+  (e.g. "wrote the first draft, which I then reviewed and reworked").
+- **You must fully understand your changes.** You should be able to explain
+  what the code does, how it interacts with the rest of the project, and
+  answer review questions yourself.
+- **Write in your own voice.** PR descriptions, discussion threads and review
+  replies should be written by you, not generated.
+
+Reviewing a change is often more work than writing it. These expectations keep
+maintainer review time going where it matters: changes that a human has
+already understood, tested and stands behind.
+
+## Community
+
+- [Forum](https://discourse.asciinema.org/)
+- [GitHub discussions](https://github.com/orgs/asciinema/discussions)
+- [Matrix](https://matrix.to/#/#asciinema:matrix.org)
+- [IRC](https://web.libera.chat/#asciinema) (#asciinema on Libera.Chat)

README.md

@@ -134,10 +134,8 @@ generation (3.x) of the asciinema CLI, written in Rust.
 The previous generation (2.x), written in Python, can be found in the `python`
 branch.
 
-If you wish to propose non-trivial code changes, please first reach out to the
+If you'd like to propose or submit any changes, please read the
-team via [forum](https://discourse.asciinema.org/),
+[contribution guidelines](CONTRIBUTING.md) first.
-[Matrix](https://matrix.to/#/#asciinema:matrix.org) or
-[IRC](https://web.libera.chat/#asciinema).
 
 ## Donations