important

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

Project management tool

We use Zenhub for our project management tool since it has a nice two way sync with Github.

caution

When starting to use Zenhub, please make sure that all the repos have been selected, and not just the default one.
Make sure that the default repo for you is the "for-zenhub" one.

Pipelines / Columns#

New Issues: When creating an issue (on Zenhub or github), this is the default column that issue goes into.
Icebox: This is meant for issues that "we will do someday".
Us vs Others: This is not a task column, but a way of organising issues that have comparison between us vs other solutions.
Always open issues: This is not a task column either, but a way of keeping track of important resources & checklists or for issues that are continous in nature like this one.
Backend SDK: Issues related to any of the backend SDKs like node or golang go in here.
Frontend SDK: Issues related to any of the frontend SDKs like supertokens-auth-react or supertokens-website go in here.
Java core: Issues related to the Java core go in here.
Documentation: Issues related to our website docs go in here.
SaaS / api.supertokens.com: Issues related to our managed service / API layer go in here. This is not related to any of the SDKs we have.
Website: Issues related to our website that are not related to docs come here. So anything to do with the home page, (post) sign up page, blogs, etc.. come here.
In progress: All issues / PRs that are currently being worked on by at least someone in the team.
Review / QA: Issues that have waiting for review. Issues are moved here ideally after the author thinks that the task is over, but sometimes multiple review steps are required so an issue can be moved here even if not complete.
Ready to push to prod: Issues that are reviewed and approved, but cannot be closed / merged because there might be other related issues that are still being worked on.
test.supertokens.com: Issues that are on the test site and not on the production site.
Closed: Closed issues. An issue may be closed even if not released yet.

Sprints#

We have weekly sprint meetings where we assign issues to each team member. Issues that are not completed in a week automatically carry on to the next week's sprint.

Sprints are from every Monday to Friday.

Estimates#

When creating an issue, we can assign estimate points to it. This is an estimate of how long the issue should take. It ranges from 1 to 40 points and we define 21 as an issue that will take one week to complete. 10 is half a week, 5 is one day and 1 is a up to a few hours.

Epics#

Epics are a collection of issues or epics. Think of them as a "large project" like creating a new SDK or a new recipe, or a new "large" feature.

They should always be created in the private repo (called for-zehub), and should always have a start and end date so that we can keep track of progress.

Any issue related to an epic must then be linked to its epic.

Creating an issue#

important

Always use Zenhub to create an issue. Never use GitHub directly. Issues created on Zenhub will automatically be created on GitHub too.

1) Click on the "New Issue" green button on the top right.
2) Select the correct github repo to create the issue in (the "Create In" option). If the issue needs to be private, choose the "for-zenhub" github repo. If you are unsure about which github repo to create an issue in, ask someone via Slack.
3) Select the correct Pipeline (Column) for this issue. You will mostly NEVER want to leave it in the "New Issues" column.
4) If the issue is high priority, click on the pin icon on the top right. This will pin the issue to the top of the pipeline you selected.
5) Assign a "bug" label if the issue is a bug.
6) Optionally Choose an assignee, or assign it to yourself.
7) Optionally add this to the current or next week's sprint.
8) Assign an estimate to the issue
9) Optionally assign an epic to the issue
10) Write a clear title. Try and make sure that it would make sense to others.
11) Write a detailed description. Put in as much information about the problem / feature / bug etc.. so that anyone reading it can understand and give their thoughts. This is especially true if the title is not super clear. Use the description space to also make a checklist of TODOs if necessary.

Creating an epic#

important

Always use Zenhub to create an epic. Never use GitHub directly.

1) Click on the plus green button on the top right and then "Epic"
2) Always keep the "Creat in" option to for-zenhub
3) Always keep the Pipeline to "New Issues"
4) Optionally Choose an assignee, or assign it to yourself.
5) Write a clear title. Try and make sure that it would make sense to others.
6) Write a detailed description. Put in as much information about the problem / feature / bug etc.. so that anyone reading it can understand and give their thoughts. This is especially true if the title is not super clear. Use the description space to also make a checklist of TODOs if necessary.
7) Click on the "Create an Epic" button and then post that, add a start and end date to the epic.

After an epic is created, you will want to think of all the sub tasks it has and create an issue per sub task. Even if the task is doing research work and not actual documenting / coding, that is worth creating as well cause in such issues, you can write down what you found out and have a discussion more easily.

Creating a PR#

Please choose the correct base and target branch. See this to know how to do this.
Link to the associated issue(s). If there are none, create one.
Fill in all parts of the PR template.
If the branch is not ready for review, make it a draft PR.

important

A PR should have minimal code changes - only related to one issue (as much as possible possible). Putting this another way, do not combine multiple independant issues into one PR.
For SDKs and the core repos, never create a PR to the master branch. Always to a custom branch to a custom branch, or from a custom branch to a X.Y branch. Merging with master happens from an X.Y branch during the release process.
A PR should aim to have at max 10-20 src (non build) file changes.
It is VERY important to think about how you will be breaking down the issue into PRs so that it is easy to review them.

How to organise your PRs#

When starting work on an issue, if the issue is small (max 10-20 src files change), you can create a single PR and then be done with it.

If the issue is bigger, then create an "issue base branch". This branch is a clone of the X.Y base branch. All your PRs for this issue would be targetting to the issue base branch, and would be merged into the issue base branch. Once the issue is complete, the issue base branch will be merged to the X.Y branch it came from.

An example:

We want to add a new recipe (call it recipeX) to the core that has 3 new APIs.
We start by taking the latest X.Y branch in the core repo and creating our issue base branch. We call the branch "recipeX".
Now we create a new branch from recipeX and call it recipeX-api1. This will contain the code for the first API we want to make for this recipe.
We issue a PR from recipeX-api1 -> recipeX.
Once this is reviewed, we merge the PR.
Then we do the same for the other APIs (branches recipeX-api2 and recipeX-api3).
Finally, once the recipe is done, we methe recipeX into X.Y.

In this example, it's possible to be working on api1 and api2 together where api2 depends on the completion of api1. In this case, you would issue a PR from recipeX-api2 -> recipeX-api1 -> recipeX. When recipeX-api1 is merged into recipeX, the target for recipeX-api2 is automatically updated to recipeX.

Dealing with review comments in a PR#

A PR can only be merged once all of its review comments are resolved. Resolving the review comments of a PR (from source branch X) should happen: 1) As new commits in that PR 2) Via a new PR whose target branch is X.

You should go with method (1) if the fix to the comment is "small", else you should use method (2).

When starting work on an issue#

In this event, be sure to move that issue to the "In Progress" column. Likewise, if something is "In Progress", but is actually not being worked on (because maybe something more important came along), then move it back to the right column.

Move an issue for reviewing#

Once an issue has been completed from your end, or if you need review on whatever has been done, then you should move that issue's PRs from in progress to "Review/QA" column.

Once the PRs have been reviewed by the reviewer, they will move the issue back to the in progress column or to the "ready to push to prod" column.

You can find a PR on zenhub by searching for it, and it should be in the new issues column by default.

Done with an issue, but not released yet#

Issues / PRs of this type go into the "Ready to push to prod" column. These are essentially reviewed and approved, but can't be closed or merged because there are other closly related issues / PRs that have not been completed.

An example of this is that if a plugin-interface PR is approved, but the corresponding core / db plugin PRs are not approved, we cannot merge the plugin interface PR as merging only that will cause build failures.

When to close an issue or merge a PR#

When an issue or a PR is approved and can be closed merge, we should do so, even if it's going to be released yet.

This is a bit counter intuitive but it is done so that we can indicate to zenhub that issues are closed as part of sprints / epics so that it can give correct performance reports.

important

Sometimes issues entail code and doc changes. So in this case, the code change PR can be merged into it's right X.Y branch, and the doc PR can be left opened. The issue itself can be closed.

Then when we are releasing the SDKs, then the doc PR can be merged to master and released as well.

Other important points#

When referencing / linking github issues or PRs together, never use the zenhub link for the issues / PR. Instead, always use the GitHub links.