Skip to main content

Shipping Things

This document defines steps to ship things for our users.

1. Decide What to Solve

Every thing starts from deciding what problem to solve. This decision is mainly done by the following process:

  1. PdM: decide core issues to solve
  2. PdM and each SWE: discuss what to solve mainly asynchronously and formulate it as a project
  3. PdM: register all the projects to our GitHub project dashboard before the beginning of each week.

The important part of this process is transparency of (1) and facts behind (1). We don't do special on these points until first release, but we will definitely start to make a foundation to manage them after that.

2. Build and Ship Little by Little

Now that you succeeded in having a good problem, the next task is to build and ship a solution for that.

One of the major challenges we face here is the balance of quality and speed. With no checks in place, everything's gonna be be broken little by little. If we could spend 10 years only for checking the quality of what we've done, we would be able to get rid of any errors, whereas it would be same as that we will never release anything!

Instead of these too-too strategies, we iterate incomplete but fast development and review as possible. What we do is the iteration of the following steps to solve one problem:

  1. Break a project into steps
  2. Discuss with your team members if needed
  3. Create your own branch
  4. Write a Code
  5. Submit a pull request
  6. Get a quick review
  7. Get the PR merged

2.0 Break a Project into Steps

The first thing you'll do is breaking your project into some small and meaningful steps. You may not need to split the project when your project does not involve with complex issues or multiple components.

2.1 Discuss with Your Team Members If Needed

A great developer shares their idea on the project with their team members before starting to write a code once they feel like there's "uncertainty" to some extent.

Quick Discussion in Slack

Even a small project may need you to tell one or two words in Slack or GitHub issues.

  • Example: "I'm just gonna add a gRPC method like Copy(src workflow.Workflow, ...) to workflow service to allow users to copy workflows. Thoughts?"

Design Docs in GitHub

If your project involves with a complex issue with relatively larger "uncertainty" and implementations may take a long time, writing a design doc would be a good choice for you.

  • You can put your idea to the corresponding GitHub issue.
  • Note that our team does not have a template for design docs as of now.

Typical topics in design docs are:

  • Background contexts; Why is the feature/change required? Who is it for?
  • Overview of your design
    • Expected user experience; In a macro point of view, what does the feature/change look like? How does it impact on users?
    • Expected internal change; How may it add, extend, and deprecate existing microservices?
  • Alternative approaches; Is there any other approach to achieve the same goal? What does it look like? Is there any tradeoff?
  • Security considerations; Is there any security considerations? Or do you need to ask some experts on this point?

When our engineering team starts to have 4 full-time employees, we may need to define who to discuss here.

2.2 Create Your Own Branch

Once your team formed a rough agreement on what you'll do, please create your own branch and push it to origin to tell your team members that you've started the development.

Your branch will be short-lived, and all commits in the branch will be squashed on merge. Hence your branch has no restriction at all. For instance, there's no restriction on commit messages -- just commiting random changes with a message like hoge or fuga is totally okay.

2.3 Write a Code

  • Write, write, and write!
  • A code here includes infrasturcture settings, unit tests, as well as application logics.
  • For coding convensions, see this page

2.4 Submit a Pull Request (PR)

  • The base branch should be v2.
  • The title should follow conventional commits.
  • The PR should have at least one reviewer.

We don't maintain CODEOWNERS as of now. This is because we're too small to do that.

2.5 Get a Quick Review

Your PR will be reviewed quickly by reviewers.


TODO: more guide is needed.

2.6 Get the PR Merged


Allowed merging method: sqaush merging

3. Review the Whole


TODO: this section will be filled after introducing feature flags

4. Ship Completely


TODO: this section will be filled after introducing feature flags