Skip to content

Instantly share code, notes, and snippets.

@joethrive

joethrive/Hanbook.md

Created February 9, 2021 12:59
Show Gist options
  • Save joethrive/e9dda91ea433461333d6fa06e0689248 to your computer and use it in GitHub Desktop.
Save joethrive/e9dda91ea433461333d6fa06e0689248 to your computer and use it in GitHub Desktop.
Download ZIP
Engineering Handbook
Raw
Hanbook.md

Table of Contents

Introduction and Purpose

The Thrive Engineering team is responsible for implementing our company's roadmap, maintaining our existing systems, prioritizing feature work, recruiting top talent, and many other things.

The purpose of this document is to provide a place to keep important information about how our team operates in a central, easily-updatable place.

Conventions

This document is structured as a single-page, internally-linked markdown document. We keep it in a single page so that it can be exported as a PDF, printed for distribution, etc.

Here are some key conventions that are used throughout the document:

  • Code is formatted like this
  • Top-level (# or ---) headings should be linked in the table of contents, in the order in which they are written
  • The print margin is set at 90 characters. Wrap lines beyond that with a \n newline.
  • Sections that are incomplete should contain TODO in place of their content.

Contributing and Updating

To update this document, fork the repository just as you would any other repository. You may then make your edits on a branch in your own fork, and submit a pull-request for review by senior members of the team.

Do not commit directly to the main thrive-commerce repository.

Team Mission and Values

It's important as an organization that we write down our mission and values to help guide our culture. We should revisit this often, and keep both the documented version, and the real-life version aligned.

Mission

The mission of the Thrive Engineering team is to build, deploy, and maintain world-class software solutions that support our company's goals, in the most efficient way possible.

Values

To Thrive Engineering, our core values are very important. They help us guide our culture, and ultimately provide a direction for our processes, policies, etc.

We value:

  • The team over the person
  • Process that supports autonomy
  • Engineer empowerment, both to succeed and to fail
  • Simplicity
  • Efficiency
  • Automation and repeatability
  • Using the right tool for the job

On-boarding

If you're reading this section, then you must be a new member of the Thrive Engineering team, so welcome!

Here are the things you'll need to setup to get started:

Accounts

You'll need accounts for the following systems:

  • G-Suite (includes access to Clubhouse)
  • Github
  • Jenkins
  • AWS IAM
  • Slack

Also, speak to your manager about obtaining the keys.zip file and how to use it.

Hardware

Thrive does not provide company-purchased hardware to employees. Please bring your own device with you each day. We recommend full-disk encryption, and password protection, as your device will have company source code on it.

Note that you may wish to create a new user or a new virtual machine to host Thrive-specific code on, but we leave this choice up to you.

Office Access

The building locks at night, so you'll need a swipe card for the main entrance. You'll also need an office door key.

Tooling

We do not have a hard list of tools, languages, frameworks, etc. that a member of the team can use. One of our core values is using the right tool for the job, so if we're not doing that, speak up!

We do however have a standard set of tools for our common tasks, outlined below:

  • G-Suite: All communication, calendaring, documents, file sharing, etc.
  • Clubhouse: All engineering task management and prioritization.
  • GitHub**: Source code management and review
  • Jenkins: Build and release automation, testing, etc.
  • Useful local tools
    • Rbenv: Manage multiple ruby environments and easily switch between them
    • nvm: Manage multiple NodeJs environments and easily switch between them
    • docker: Build and run container images

Process

One of our core values is that we use process to support autonomy. We do not believe in process just for process' sake. Autonomy in an engineering team can only exist if it is supported by a process that provides both accountability, and visibility. By that, we mean: As items move through our development life-cycle, it should be easy to see who is working on an item, and what its status is.

Our process is described by the three sections below, meetings, intake and execution, and code.

Meetings

Until someone figures out a better way for people to collaborate, every organization has meetings. At Thrive, the engineering team has the following key meetings

Daily-sync

Monday thru Thursday we all meet to discuss progress, blockers, etc. We also triage any bugs that have been submitted during this time.

Grooming

Every other week we meet to groom the backlog, ensuring that it is in the proper order, and that all items are still pertinent. Anything that's ready to work on can be moved to TODO status during this time.

Intake and Execution

This section details how we take in new work, bugs, etc. and how we then execute on it. For the time being, we're running the Kanban agile methodology, shipping code whenever we feel that it's ready.

The three areas of focus with regards to work management are:

Bug Triage

This process is guided by the board called "Bug Triage." Bug Triage represents accepting or rejecting bugs, and categorizing their priority. This should be a lightweight task, and should not be used to dive too deeply into the bug itself.

Feature Intake and Prioritization (Epics)

This process is guided by the board called "Epics." Feature intake represents new work coming into our team. Epics represent work that requires multiple tasks, and is generally client-facing. Prioritization of the epics can happen during intake, or during backlog grooming. The overall status of a feature should be able to be determined from viewing the "epics" board.

Work Items

This process is guided by the board called "Work Items." A work item is a task that has output of some kind (whether that's communication, code, documentation, etc.) and is assigned to a specific person. Work items can be "Tasks," "Sub-tasks," "User stories," etc.

Most of an engineers time is spent working on "work items" and should be reflected by the project management tool being used.

Code

TLDR:

  • Always work in a fork, on a feature branch
  • Submit PRs
  • Never merge your own PR
  • Commit messages and branch names should follow the format described below

There are an infinite number of ways to manage a codebase. The way we like best is Git Flow. We don't follow it strictly, but the main idea is that you should be working in your own fork for everything, and all work should be done on feature branches.

For versioning, we follow do not use version numbers. All modules are versioned by their git commit hashes.

Commit messages should include a few key pieces of information:

  • Clubhouse ticket IDs (if any)
  • A one-line (on the first line) description of what changed
  • A bulleted list of any details or ancillary changes

Example:

TE-1234 added some awesome feature

 * changed the way X works
 * built a new Y that will handle all new requests for Z

Branch names should include the top-level Clubhouse ID that you're working on, whether that's a story, epic, etc., and a short description of the item.

Example: structured_markup_TE-37

Policies

TODO

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment