Repository files navigation

💡NOTE

The Whist Browser project was archived in December 2022. The founding team behind Whist has since launched a new project, ParadeDB -https://github.com/paradedb/paradedb.

This repository contains the bulk of the code written by the Whist team for the Whist Browser and its Cloud Tabs framework, following amonorepo structure.

Project	Code Coverage
backend/services
protocol
Overall

• Repository Status
• Repository Structure
• Development
  • Branch Conventions
  • Commit Conventions
  • Hotfixes
  • Promotions
  • Styling
• Publishing

The Whist monorepository contains many subprojects:

For a more in-depth explanation of each subrepository, see that subrepository's README. Note that there is also additional documentation for some subrepos (and other Whist repos) atdocs.whist.com:

• docs.whist.com/backend/services
• docs.whist.com/protocol

To get started with development, you will have to clone this repository and navigate to a specific subrepository. On Windows, you will have to installgitbash. It is recommended to useSSH, so that you don't have to type in your GitHub password on every push.

While it is likely that you will work on a feature that touches multiple subrepositories, each subrepository has its own development and styling standards which you should follow, in addition to the usualWhist Engineering Guidelines.

To avoid pushing code that does not follow our coding guidelines, we recommend you install pre-commit hooks by runningpip install pre-commit, followed bypre-commit install in the top-level directory. This will install the linting rules specified in.pre-commit-config.yaml and prevent you from pushing if your code is not linted.

NOTE: Also, once you clone the repo rungit config pull.ff only inside the repo. This will help prevent pushing unnecessary merge commits (see below).

• prod -- This branch is for Stable channel only, do not push to it.
• staging -- This branch is for Beta channel only, do not push to it. It gets promoted toprod periodically.
• dev -- This is our main development branch, PRs should be made to this branch, and it builds the Nightly channel. It gets promoted nightly.
• All other branches are considered feature branches. They should be forked off ofdev and PR-ed intodev.

Feature branches are named as follows:

• Project-specific feature branches (i.e. those restricted to a single top-level directory in the repo) are named in the form<author>/<project>/<feature-verb>. For instance, a branch authored by Savvy and designed to make the Host Service llama-themed would be calleddjsavvy/host-service/add-llama-theme.
• Broader feature branches that touch multiple projects should be named in the form<author>/<feature-verb>.

Note that the last part of the branch name should almost always be anaction instead of an object (i.e.add-llama-theme instead ofllama-theme). This makes commit logs much easier to parse.

You're free to modify your own branches in any way you want. However, do not attempt to rewrite history on our common branches unless you have a specific reason to do, and the team's approval.

We explicitly disallow merge commits on this repository, and all branches should be either squash-merged or rebase-merged, to avoid messy git histories with lots of "Merged branchdev in ....". The commandsgit rebase is your friend, and to avoid accidental merge commits when pulling, you can rungit config pull.ff only in your local repository.

Clear commit logs are extremely important in a monorepo, due to the number of different active projects that share the git history. Like branch names, commit messages should be descriptive and contain enough context that they make senseon their own. Commit messages like "fix", "works", or "oops" can be annoyingly unhelpful. Even something as innocuous-sounding as "staging merge" can be confusing -- are we merging intostaging, or mergingstaging into another branch? What other branch(es) are involved?

Some good rules of thumb:

• Commit messages, like branch suffixes, should beactions instead of objects.
• Add as much context as you possibly can.
• Forget the "50 characters max" or whatever artificially-low number GitHub and Linus Torvalds start complaining at. It's far more useful to have a clear, contextualized commit message that spills over than an artificially terse mess.

To view a log of only the commits affecting a given file or subdirectory, use the double-hyphen syntax forgit log:git log -- <path>.

Eventually, but hopefully rarely, production will be on fire, and we will need to deploy a quick fix ASAP. To do so, branch your changes off ofprod with the prefixhotfix/<your-fix>, and PR your branch directly intoprod. Once the fix is thoroughly tested, we'll merge it intoprod and mergeprod back intostaging andstaging back intodev to resolve the git history.

Once ourdev branch is stable and we're ready to bring our new changes out into the world, we'll promote it todev. This can be done by opening a promotion PR via the following URL:

https://github.com/whisthq/whist/compare/staging...dev?expand=1&template=promotion.md

To open a promotion PR fromstaging toprod, simply update the values in the above URL. Once the promotion PR is open and well tested, it can be merged from an engineer with force-push access via:

git checkout staginggit merge dev --ff-onlygit push -f

Please refer to a project's subrepository for the associated styling guide. All work done on this monorepository must follow theDocumentation & Code Standards and theEngineering Guidelines.

Each of common branches,dev,staging, andprod get deployed automatically via GitHub Actions to our respective environments on every push to the respective branches, except fordev which gets published nightly. This process is quite complex, and is defined in.github/workflows/whist-build-and-deploy.yml.

If something goes wrong in the continuous deployment pipeline and any job fails, it is possible to manually trigger a specific job of the workflow via the GitHub Actions console.

Enjoy!