Contributing to Replay

Why Contribute to Replay?

Welcome to Replay, a semi-open-source platform that allows users to record and replay web applications and JavaScript programs. It is a powerful novel tool that helps developers analyze dynamic application behavior, catch flaky bugs and ultimately improve the quality of their application. By contributing to Replay, youโ€™ll be making a difference in the lives of developers around the world.

Community Etiquette

Being part of a community means following some basic rules and etiquette:
  • Feel free to introduce yourself in our #introduction (or #gsoc) Discord channel.
  • Please note that, as a small team, we generally do not have the capcity to help everyone is new to the project. We generally cannot (i) help solve any small problem anyone might encounter, (ii) work with everyone on their PRs, (iii) service everyoneโ€™s DMs, or (iv) provide custom introductions to our codebase.
  • Please do not DM anyone without prior consent. As is common in open-source communities, not following this very simple rule might get you a temporary ban.
  • Before asking for help, be sure to have carefully read our official docs and guidelines.
  • If you encounter actual problems in the code, please file a proper bug report in the relevant GitHub repositories.
  • If you encounter a problem in the docs or setup instructions, feel free to report in the relevant Discord channels.
  • If you have a question or other important topics of discussion, there is a good chance that others have/had the same or similar questions or thoughts. We thus encourage everyone to share in #gsoc. This way, we can best use our small team to dissiminate information among the broader community.
  • Lastly: We very much appreciate seeing and encourage all members of the community helping one another.

Coding + PR Guidelines

Help, my pull request got rejected! Contributing to Open Source can be challenging. Mistakes โ€“even small onesโ€“ can prevent a change from being accepted. We ask that you follow the rules and guidelines below to make the process as smooth as possible, and avoid unwanted rejections. WARNING: Even if you follow all the rules, commits might still get rejected. That does not say anything about who you are as a person, nor does it mean that your PRs are not welcome. We are all human beings here, and we are all imperfect. However, sometimes we just donโ€™t have the capacity or bandwidth to work with you through the many subtle changes and susbequent problems that your PR can cause. If you feel that your PR has been rejected unfairly, you can (carefully) ask on Discord: If you are an experienced developer, ask in #development. If you are a beginner, please ask in #gsoc, where we currently handle a large influx of inexperienced contributors. We try to respond to all requests, but we sometimes get a bit overwhelmed. Please be patient, tag only sporadically, and never DM people without consent. Thank you!
  1. Before posting a PR, please run all lint , typecheck and test steps. For devtools those are:
    1. Run TypeScript (npm run typecheck) and Lint (npm run lint) to check for errors and formatting issues.
    2. Run unit tests (npm run test) to check if change broke other code.
    3. Add new unit or e2e tests for your code and make sure that it also passes. This helps the reviewer. It also verifies that your code works correctly now and does not get broken by future changes. Here are some notes by Brian Vaughn on the matter.
  1. Open a PR on GitHub with your changes. The PR description must include the following:
    1. Link to the GitHub issue you are fixing (and any other relevant links)
    2. Show how your change effects the UI/UX. (Screenshots, short Loom videos and Replays are good ways to show changes.)
  1. If you are a GSoC applicant (or generally not a seasoned developer with a lot of OSS experience): Send a message to the #gsoc Discord channel with a link to your PR. This is a vital step that allows our GSoC mentors and OAs help with the triaging process and alleviates some of the pressure coming from a sudden swell of PRs in our open source repos.

Before You Start Contributing

Here are a few tips to keep in mind as you contribute to Replay:
  • Read the Documentation: Before you start contributing, read the documentation and Reference Guide for the project youโ€™re interested. This will help you understand how the project works and what you need to do to contribute.
  • Start Small: If youโ€™re new to open source, start with a small project. This will help you get comfortable with the contribution process and build your skills.
  • Ask for Help: If you get stuck, donโ€™t be afraid to ask for help. Our community is friendly and supportive, and weโ€™re always happy to help new contributors.
  • Be Patient: It can take time for your pull request to be reviewed and accepted. Donโ€™t get discouraged if it takes a while. Keep working on other projects in the meantime.

Where is the Code?

Replay has multiple open source projects, including the Replay Browser and the web app front end!
  • /devtools (Web app with developer tools built on the Record Replay Protocol)
  • /replay-cli (CLI tool for managing and uploading recordings. This also holds several packages related to recording cypress and other types of tests with Replay and more.)
  • /replayable (A curated list of maybe (hopefully) interesting public Replays, useful for practicing)
  • /gecko-dev (The current main Replay browser, based on Firefox)
  • /chromium (Our up and coming Replay browser, based on Chromium)
Check out more of our public projects on GitHub.