Skip to main content
important

This is a contributors guide and NOT a user guide. Please visit these docs if you are using or evaluating SuperTokens.

How git is organised

This section contains information about how all the git repos are organised and their relation with versioning and releases.

important

We always use the master branch as the default branch. Not the main branch. Any content in the master branch represents the latest released code.

About branch and versions#

Each version of the repo is represented by its version branch. For example, if a branch is named 2.8, then it will contain versions of the code 2.8.X (example, 2.8.0, or 2.8.1 or so on..)

When creating a new PR, you want to do one of the following:

  • If the PR is a patch (increment of Z in X.Y.Z), then you want to choose X.Y as the base and target branch for the PR. Note that if branch X.Y doesn't exist, then your probably doing something wrong.
  • If the PR is a minor change (increment Y in X.Y.Z), then you want to create the new X.Y branch from X.(y-1) branch. And use the new X.Y branch as the base and trarget of your PR. For example, if the latest version of a repo is 2.3.4 and we want to make a change such that the version changes to 2.4.0, then first, we will create branch 2.4 from branch 2.3, and then issue a PR whose base and target branch is 2.4.
  • If the PR is a major change (increment X in X.Y.Z), then you want to create the new X.0 branch from (X-1).Y branch, and use the new X.0 branch as the base and target branch for your PR. For example, if the latest version of a repo is 2.3.4 and we want to make a change such that the version changes to 3.0.0, then first, we will create branch 3.0 from branch 2.3, and then issue a PR whose base and target branch is 3.0.

When a version is to be released, if it's the latest unreleased version, it will be merged to the master branch. The associated version branch will still remain.

There can be situations in which we want to release a new patch fix for an older version. In this case, the patch fix will remain in the X.Y branch and not be merged with master. Releasing to a distributor (like npm) should not be tied to pushing to master. Instead, we tie it to tags.

Picking the right base and target branch#

important
  • The base branch is one where you create your own branch from
  • The target branch is one where you want your PR to get merged.
  • The base and target branch should always be the same.

For NON breaking changes, you want to do the following:#

  • Run git tag. This will list all the current tags for the repo
  • Find the latest vX.Y.Z branch. Sometimes they can be in the middle of the list too.
  • If this is a minor change:
    • See if a branch X.(Y+1) branch exists. If not, create one (from the latest vX.Y.Z branch).
    • X.(Y+1) is your base and target branch.
  • If this is a patch change:
    • See if a branch X.(Y+1) branch exists. If yes, your new base and target branch is X.(Y+1)
    • Else your new base and target branch is X.Y.

For breaking changes:#

  • Run git tag. This will list all the current tags for the repo
  • If next-breaking-change exists, that is your base and target branch.
  • Else, find the latest vX.Y.Z branch. Sometimes they can be in the middle of the list too.
  • If X.(Y+1) exists, use that to create the next-breaking-change branch. Else use X.Y to create the next-breaking-change branch.
  • next-breaking-change is your base and target branch.

About tags & releases#

There are two types of tags:

  • Dev tag (format: dev-vX.Y.Z)
  • Release tag (format: vX.Y.Z)

Dev tag#

A dev tag, dev-vX.Y.Z, can only be added to a branch X.Y, and there should be appropriate checks in place to make sure that this is enforced.

Once a dev tag is added, it runs the CICD pipeline for unit and integration tests for that version.

Release tag#

Once a dev tag has been added, and the tests have finised running successfully, then we can remove the dev tag from the commit and add a release tag instead.

A release tag, vX.Y.Z can only be added to a commit which has a dev tag dev-vX.Y.Z AND if the tests have passed (checked via an API call to api.supertokens.com).

Once a release tag is added, two things should happen:

  • If this is the latest version, we should merge this branch into master.
  • We release this version to the distributor (for example npm).
important

This operation is sensitive, and should only be allowed by individuals who have the right SuperTokens API key.

About hooks & scripts#

Each repo has:

  • pre commit hooks: At a minimum, these make sure that:
    • the code compiles
    • the code is properly formatted
    • the versions everywhere in the code are appropriate
    • the branch being commited to tallys with the version of the code (in case the branch is of the format X.Y).
  • addDevTag script:
    • This script does all the checks to make sure that we can add a dev tag to this commit, and adds a new tag
  • addReleaseTag script:
    • This script does all the checks to make sure that we can add a release tag to this commit, deletes the dev tag, and adds a new release tag + merges with master if needed.

CICD#

Once a tag is added to a commit, the testing / releasing process begins. We use circle CI for this, and hence you will find a .circleci folder at the root of most of the repos.

You can learn more about how tests are done in the testing section of this doc.

Readme.md#

The readme of a repo is very important and it should highlight:

  • The SuperTokens logo
  • A description of what the purpose of this repo is
  • Links to documentation for this repo
  • Optionally a list of contributors (as is the case with supertokens-core)
  • How testing is done (if necessary)
  • How to contribute
  • How to contact us
  • Who the authors are

Contributing.md#

Should highlight how to setup the dev env, how to make code changes, and how to run tests.

Permissions and setting sections#

  • The supertokens/core team should have write access to the repo
  • Branch persmissions:
    • No rewriting history of deleting of master branch
    • No rewriting history of deleting of branches whose format is X.Y.
  • Auto delete of branches when merged PRs

PR actions#

We want make PR review as easy as possible. This means automating as many checks as we can, or making checking easier. Some examples:

  • Making sure that changelog has changed via github actions
  • For PRs to docs, we use netlify to deploy a site containing the changes made in the PR so that one can see the rendered changes properly.

Repo playground#

An SDK usually contains a "playground" file(s) (in the test folder). This allows you to make sure that the types exposed by the SDK are correct.

Which frontend SDK do you use?
supertokens-web-js / mobile
supertokens-auth-react