Skip to main content

Shipping Things

This document defines steps to ship things for our users.

1. Decide What to Solve​

Everything starts from deciding what problem to solve together with the Product Manager (PdM) and Software Engineers (SWE). This decision is mainly done by the following process:

  1. PdM: decide on and communicate the core issues for the team to solve after customer research, feedback analysis, and strategic business planning
  2. PdM and each SWE: discuss what to solve (mostly asynchronously) and formulate it as new user story
  3. PdM: validate the user stories that best align with which customer value and feature set, and help create and assign them to applicable milestones on the roadmap for tracking
note

Transparency and fact-driven decision making are important to this process. We will strive to encourage one another to uphold these points throughout our development process as a part of our maturing foundation for engineering excellence.

2. Build and Ship Little by Little​

Now that you succeeded in articulating a good user story solution to a good problem to solve, the next task is to build and ship the solution.

One of the major challenges we face here is the balance of quality and speed. With little formal checks in place, everything will be broken little by little. If we could spend 10 years only checking the quality of what we've done, we may be able to get rid of many errors, but we would never release anything! The user story should also be brief but is essential that our ideas clearly and concisely articulate how we intend to solve a customer's real problem and help them accomplish their tasks.

Our development process is also emergent, where we often iterate in incomplete but in rapid development and review sequences a quickly as possible. The iteration process roughly follows these steps to solve a problem:

  1. Break a user story into steps and assign issues to an applicable milestone for tracking
  2. Discuss with your team members as required
  3. Create and share your own branch
  4. Write some code
  5. Submit a pull request, also assigned to an applicable milestone for tracking
  6. Get a quick review
  7. Get the PR merged

2.0 Break a User Story into Steps​

The first thing you'll do is break your user story into some small and meaningful steps. You may not need to split the user story when it does not involve complex issues or multiple components. (We can rely on the team to help make that decision!)

We also rely on assigned GitHub milestones at the very least as a primary means for tracking progress and effort for key customer impacting milestones. This allows us to quickly work together and aggregate an emerging part of the narrative of our efforts, without having to hand-curate so many manual lists. It may also help to consider if we are already working on something similar and if the proposed work introduces new effort or may overlap existing effort. If a milestone does not yet exist, the PdM can help you create one.

2.1 Discuss with Your Team Members as Required​

A great developer shares their user story ideas and strategy with their team members before starting to write a code especially when there is some "uncertainty" or need for clarity. There may also be someone working on something similar. We cannot know what we do not know, and rely on the team to help provide fresh perspectives.

Quick Discussion in Slack and GitHub​

Even a small user story may require you to mentioning just a few words in Slack or GitHub issues.

  • Example: "Our users need to be able to copy workflows, so I'm just gonna add a gRPC method like Copy(src workflow.Workflow, ...) to the workflow service to enable them. Thoughts?"

Additional In-Depth Design Docs​

If your user story involves complex issues and logic with a relatively larger degree of "uncertainty", and with implementations requiring long lead times to completion, then writing an in-depth design document would be a good choice for you.

  • You can still put your potential user story idea in a corresponding GitHub issue.
  • The user story template will encourage you to outline key details about about the problem and solution spaces
  • Note that our team does not have a specific template for design docs as of now and rely on emergent design through diagrams and white-boarding as we share ideas with the team
info

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?
    • Simple architectural diagrams: The first two levels of the C4 model is a great place to start
  • Alternative approaches: Is there any other approach to achieve the same goal? What does it look like? Is there any trade-off?
  • Security considerations: Is there any security considerations? Or do you need to ask some of our own experts on this point? Be transparent!
note

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

2.2 Create Your Own Branch​

Once them team has reached a general consensus on what to do, please create your own branch and push it to origin to tell your team members that you've started the development and to share your work as you go along.

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

2.3 Write Code​

  • Write, write, and write!
  • The code here can include infrastructure settings, unit tests, as well as application logic.
  • For coding conventions, 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.
  • The PR should be assigned to an applicable milestone for tracking
note

We don't maintain CODEOWNERS as of now, as our team size does not yet require it.

2.5 Get a Quick Review​

Your PR will be reviewed quickly by the assigned reviewer.

note

TODO: more guide is needed.

2.6 Get the PR Merged​

note

Allowed merging method: squash merging

3. Review the Whole​

note

TODO: this section will be filled after introducing feature flags

4. Ship Completely​

note

TODO: this section will be filled after introducing feature flags