Contributing to asciinema

Thank you for your interest in contributing! This document describes how contributions work across the asciinema ecosystem:

asciinema - the CLI: terminal session recorder, streamer and player
asciinema-player - the web player
asciinema-server - the hosting and streaming platform
agg - the GIF generator
avt - the virtual terminal library
docs - 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 or on the forum.
Questions and help requests belong on the forum or in the GitHub discussions "Q&A" category. 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

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.

If you're not sure whether something is a bug, or you can't reproduce it reliably, start with a discussion or forum thread instead.

Proposing features and changes

For anything beyond a small bug fix, please talk to us before writing code:

Start a thread in the "Ideas" discussions category or on the forum.
Describe the problem you're solving, your proposed approach, and who would benefit from it.
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.

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.

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 your change is specific to your workflow, or it's something we can't adopt right now, maintaining it in your own fork is a perfectly good outcome, and one we genuinely encourage. The licenses give you all the freedom you need, and we're happy when asciinema code is useful even outside the main line.

Pull requests

Bug fix PRs can be opened directly; reference the issue if there is one. Feature PRs should follow a green-lit discussion (see above).

What we look for in a PR:

Keep it focused and as small as practical. We may ask for a large change to be split into smaller ones.
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
GitHub discussions
Matrix
IRC (#asciinema on Libera.Chat)

6.2 KiB Raw Blame History