Welcome! ♥ Whether you’re new to FirstPort and looking to get up to speed on how we work, or looking in from the outside (psst, we’re always hiring), it’s great to have you here.

This handbook outlines our general approach to engineering and contains everything you need to know to start shipping code at FirstPort.

Specific project detail should live with specific projects - but everything should inherit and extend the principals within this handbook.

All updates to the handbook are peer-reviewed by engineers at FirstPort and it represents our shared wisdom and values about our development practices, culture, and how projects should be put together.

For advice on how to contribute, see the README.md in the project repository

An Important Note

One of the key aspects of FirstPort is individuality. While we’re publishing this site with both descriptive (“this is how we work”) and prescriptive (“this is how we want to work”) information, it’s important to note that these are guidelines, not rules. We often debate various things internally, and projects can have inconsistencies from each other. Sometimes, this is a good thing. The flip side of consistency can be monoculture, where experimentation is discouraged.

Engineers can often get caught up in issues like “what’s the best way to do this?”. While we obviously want to work from the best possible starting position, there’s nothing to say you have to stay there. Take the best that’s available and run with it.

Experiment. Deconstruct. Rebuild. Blow it all away and start from scratch.

Some of the best projects come from a dissatisfaction with the status quo. If there are things in this guide you disagree with, fix them. Nothing will ever be perfect. Maybe something that’s annoying you today turns into a better tool for everyone tomorrow.

This guide is a living set of documents, and will be updated as we continue to refine, refactor, and rebuild our processes and tooling.

Q. Who can update the handbook?

A. Anyone at FirstPort. Simply branch the repo1 and have at it. When you’re done raise a pull request for review.

Q. What if I encounter code that doesn’t follow the approach in this handbook?

A. Congratulations. You have a free pass to make anything you encounter work as described in the handbook. See the charter and our commitment to fixing broken windows.

Q. Why is the handbook public?

A. By making our approach public and transparent, we hope to promote responsible practices in our approach to engineering.

There’s nothing like a little public scrutiny and critique to make us think twice about whether we are going about things in the correct way.