AIR Developer Handbook

How to use this book

Stick to conventions to be able to focus on the interesting problems.

This book should serve as a guideline for our development efforts to ensure consistency between projects. I wish it to be an ever-changing, morphing repository of knowledge acquired during our work together. Maik, May 1st 2017

Help us do better work by submitting change requests and write blog articles backing up new knowledge.

Improve it

git clone git@github.com:en-japan-air/blog.git
cd blog/_pages
vim handbook.md

For formatting the book with Markdown, refer to the Minimal Mistakes template docs.

Getting started

Welcome to AIR! :tada: :balloon:

It’s great to have you in our team. To get you started in no-time (actually more around an hour), grab a senior and go through the onboarding together.

Doing it will gain you the following perks:

  • :cat2: Access to ze internet
  • :page_with_curl: The ability to print
  • :mailbox_with_mail: Your own @en-japan.io email address
  • :cocktail: A calendar
  • :key: Accounts on Google, Slack, Lastpass, Asana and so many more
  • :moyai: knowledge about our work rules and employee evaluation system
  • :credit_card: and finally after some walking your access card

Basic system setup

Once you have received your work horse, you can tell it to:

  1. Replace the default MAC terminal with iTerm2
  2. Install homebrew package manager
  3. Install your editor of choice. Your coworkers like

and if you feel fancy, also

  1. install Aerial, a screensaver we dig

GitHub access

Ask the tech lead for a seat in our organization, by sending him your personal GitHub handle via Slack.

Github

Account setup

Make sure your git name and email are set

git config --global user.name "Your name"
git config --global user.email your.github.email@provider.com

Then you can

$ ssh-keygen
Generating public/private rsa key pair.
Enter file in which to save the key (/home/username/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):

Make sure you provide a secure provide a secure passphrase when creating your ssh-key. Do not use an SSH key without a passphrase. This will prevent someone from being able to use your keys if they are stolen.

If you already have an RSA key without a passphrase set a passphrase for it like so:

ssh-keygen -p -f ~/.ssh/id_rsa

Once you receive the email from GitHub you can login and add the above ssh-key to your account. This will allow you to access our Git repositories.

Development flow

https://guides.github.com/introduction/flow/

Repository setup

Please use the https://github.com/en-japan-air/dummy project as a start. Improve it by sending some PRs it’s way :) Also make sure to provide the basics and follow these conventions:

  1. A good name.
    If the project is split into modules, use the project name as prefix to group the repos like so:

    vibe: main application
    vibe-chrome: chrome extension
    vibe-website: landing page

  2. A clear description and some relevant tags
  3. PR and issue templates
  4. A well structured README.md

Git Tips & Tricks

The Stacks

We currently develop applications using mainly two different stacks. Talk with your peers about Pros/Cons of a stack for any given project and decide which one to use.

To keep our reference stacks up-to-date, feel free to sign up with our organisation at https://stackshare.io/air-at-en-japan-inc.

Backend driven

StackShare

Ruby on Rails / Vue.js / AWS

Frontend driven

StackShare

Firebase / React / React Native

App versioning

semver

Use the VERSION file in your repo as the source of truth for the current app version.

Code style

Editor settings

We embrace versioning our code style and therefore you will (hopefully) find an .editorconfig in most of our projects.

For everything unsupported by editorconfig, follow our code style:

  • enforce line break at end of file
  • wrap code after 120 columns

Automated linting

The respective tool must be set up for your project and be part of any CI test suite to run. For preventing code creep, such tools should also be set up to check your changes in a pre-commit hook. Whenever linting fails, deployment and/or pushing code should be prevented.

Continuous integration

TODO

Deployment

TODO

Security

  • Protect environments other than production with Basic Authentication if possible.
  • We use Snyk to periodically check our environments for outdated dependencies.

Also refer to Handling secure data on how to share passwords and handle environment variables.

Error Tracking

Ruby

We decided to use a combination of Rollbar and New Relic for our Ruby on Rails backed systems.

SPA

TODO

URL Conventions

Production https://domain.com
Staging https://st.domain.com
Development https://dev.domain.com / any

Subdomains

Production https://sub.domain.com
Staging https://sub-st.domain.com
Development https://sub-dev.domain.com / any

Regex

Regex FTW

E-Mail regex

Keep it simple. The email address spec is fairly complex, and we have seen many validators in the wild restricting valid email addresses.

.+\@.+\..+ will do the job.

Sending emails

If possible, use Mailgun for sending emails. 10.000 mails per month are free and emails can be easily processed via an API. Furthermore, it includes infrastructure to retry sending, deliver notifications to configurable hooks and parsing inbound mails to JSON. For most apps this service should be sufficient and is preferable over managing your own instance of Sidekiq/Redis.

Handling secure data

Share passwords & keys

Sharing of keys, passwords and other sensitive data must be done through our password management solution. Decide who needs access and share with the appropriate audience using access control features. We currently use LastPass.

Never share such data in any other way than described above. Never store as plain text.

Environment variables

Environment variables might be made available in the target environment through various means.

  • Travis: encrypt the variable and save a secure hash in the .travis.yml

TODO: describe flow for AWS (KMS) and Firebase

Design and you

The creative team will make available their designs through Invision. Developers can comment and inspect the design.

Every engineer plays an active role in the design process. It is your responsibility to give feedback and discuss

  • Feasibility
  • Time it will take to implement
  • If there is a better way to approach the feature

You have intrinsic knowledge of the technical possibilities and limitations of the application stack, and therefore should be able to advise all stakeholders on development efforts required, impact on user experience and share best practices for the chosen platform. If you are unsure, take some time to explore a solution as a prototype together with a designer.

Project handover

In the event that we handover a project for further development to another department or a third party, prepare a transition plan together with involved parties. Once the transition plan has been agreed on by all stakeholders, perform the transition.

  1. Always create a transition plan
  2. Also refer to the checklist for handover https://github.com/en-japan-air/commons/tree/master/Documentation/handover

Uninterrupted development

If you find yourself constantly interrupted by coworkers, managers etc during your development work and it impacts your flow, then please kindly share the research on interruptions with the respective person and explain how you would rather handle these discussions.

TL;DR

Based on a analysis of 10,000 programming sessions recorded from 86 programmers using Eclipse and Visual Studio and a survey of 414 programmers (Parnin:10), we found:

  • A programmer takes between 10-15 minutes to start editing code after resuming work from an interruption.
  • When interrupted during an edit of a method, only 10% of times did a programmer resume work in less than a minute.
  • A programmer is likely to get just one uninterrupted 2-hour session in a day

We also looked at some of the ways programmers coped with interruption:

  • Most sessions programmers navigated to several locations to rebuild context before resuming an edit.
  • Programmers insert intentional compile errors to force a “roadblock” reminder.
  • A source diff is seen as a last resort way to recover state but can be cumbersome to review

Pair programming

Pair programming rocks. Do it if you have the chance. It’s not only useful if you want to learn from someone, but even more so having experienced engineers working together solving a hard problem. Your output volume will be similar to working separately but your code quality will be much better.

If you think what you need to work on will benefit from pair programming, suggest it in the daily huddle or just ask another engineer to find the time to work together.

OSS

We are relying heavy on open source software and want to give back to the community whenever possible. Therefore it is encouraged to take the time to properly prepare pull requests for libraries we use. Fork the project, fix it and issue a PR against the original repo after testing.

If you think the public would benefit from tools or libraries we created internally, let the tech lead know and discuss with the peers if and how to open source the project. Provide the same care of documenting and repo setup as you would for our projects. Our preferred license is MIT. Once ready for publishing, ask the creative team for a cool logo and order some shirts to enjoy the fame :)

Enscalator

image-left

Make applications webscale
en-japan-air/enscalator

Enscalator is a tool to document and deploy infrastructure to AWS using a simplified Ruby template DSL.

Slack

We use Slack for communication. Be available. Use @channel sparingly. Snooze notifications if you don’t want to be interrupted (check from time to time to not miss important messages).

Projects are usually organized into the following channels:

  • project : Common discussion; business; share relevant resources and announcements
  • project-dev : Developer talk. Ask for PR reviews. Discuss dev issues. Share dev resources.
  • project-release : Release and changelog announcements. Useful for business peeps to follow deployments.
  • project-creative : Designer talk. Sneak peek into if you’re interested.