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.
git clone firstname.lastname@example.org:en-japan-air/blog.git cd blog/_pages vim handbook.md
For formatting the book with Markdown, refer to the Minimal Mistakes template docs.
Welcome to AIR!
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:
- Access to ze internet
- The ability to print
- A calendar
- Accounts on Google, Slack, Lastpass, Asana and so many more
- knowledge about our work rules and employee evaluation system
- and finally after some walking your access card
Basic system setup
Once you have received your work horse, you can tell it to:
- Replace the default MAC terminal with iTerm2
- Install homebrew package manager
- Install your editor of choice. Your coworkers like
and if you feel fancy, also
Aerial, a screensaver we dig
Ask the tech lead for a seat in our organization, by sending him your personal GitHub handle via Slack.
Make sure your git name and email are set
git config --global user.name "Your name" git config --global user.email email@example.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.
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:
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
- A clear description and some relevant tags
- PR and issue templates
- A well structured README.md
Git Tips & Tricks
Git Internals Part 1 - Objects
Our developer & dev ops talent Denis looked under the hood of git and encourages you to do the same.
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.
Ruby on Rails / Vue.js / AWS
Firebase / React / React Native
VERSION file in your repo as the source of truth for the current app version.
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
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.
- 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.
We decided to use a combination of Rollbar and New Relic for our Ruby on Rails backed systems.
|Development||https://dev.domain.com / any|
|Development||https://sub-dev.domain.com / any|
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.
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 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
- 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.
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.
- Always create a transition plan
- Also refer to the checklist for handover https://github.com/en-japan-air/commons/tree/master/Documentation/handover
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.
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 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.
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 :)
Make applications webscale
Enscalator is a tool to document and deploy infrastructure to AWS using a simplified Ruby template DSL.
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.