Vinta's Playbook

Plans and practices

contact us

"Any fool can write code that a computer can understand. Good programmers write code that humans can understand." To follow Martin Fowler's directive we try to code as smart as possible, check out how we do it:

Boilerplate

The use of our boilerplate is standard when starting new projects.

Environments

Staging

  • Should be as similar as possible to production.
  • It's OK to delete the database (but do tell the client before doing so).
  • Keys should be the same as in production (.env). If the third-party service supports test-API keys (like Stripe), use them here.
  • Like in production, developers need to receive errors via Sentry (configure it to send e-mails to the one responsible).

Server access information

  • Create a DEPLOYMENT.md file.
  • That file should explain the basics how-to of the server (how to access app code, restart/stop the server and services).

Principles

  • KISS: Keep it simple, Sweetie (not stupid!).
  • If there's no way to keep it simple, make sure there are comments.
  • Functions/methods/classes/modules must have a single concern.
  • Even commits must have a single concern, so commit as often as possible (try not to have an "and" in commit messages).
  • Every piece of knowledge must have a single, unambiguous, authoritative representation within a system. Stay DRY: Don't Repeat Yourself.
  • Reuse domain/business logic, because those must be always consistent.
  • But prefer duplication over the wrong abstraction.
  • After all, premature generalization, as well as premature optimization, is the root of all evil.
  • Because probably YAGNI: You aren't gonna need it.
  • Better to isolate code that changes often from code that doesn't.
  • And write code that is easy to delete, not easy to extend. Things change in unexpected ways.
  • Feature flags help with this. They decouple feature releases from merging branches and deploying. And help to decouple behaviors.
  • Decoupling is good if it gives you power to easily add, change, or remove code. If not, forget it.
  • Pure functions are always decoupled from state and time. Avoid side effects.
  • But remember that complex is better than complicated.
  • Write readable code. Readable code is less likely to contain bugs, because readability makes bugs more visible.
  • Know that design matters.
  • And UX matters even more.
  • All code should be reviewed.
  • All features must be manually tested before going to production.
  • And again, keep it simple.
  • Some in-depth resources related to those principles:

Style Guides

Python

JavaScript

HTML & Sass

Daily reporting

We use the IN/OUT methodology for daily follow-up with project developers, as well as the Harvest app to track how much time has been spent on the project. A quick report by the end of the day to the project manager also helps to keep the project on track.

Depending on the project, the client might have a project manager communicating in his/her behalf. Whenever that is the case, the daily report should be sent to either the project manager or to the client, at their discretion. Among the Things that should be addressed are: features developed, bugs fixed, PRs submitted, PRs merged, PRs reviewed, deployments, problems encountered. Example:

  • Merged PR on views authentication [link to Trello card].
  • Fixed header responsiveness bug on home page.
  • Deployed to staging.

Developer’s attributions

  • To Be able to contact the client directly to settle doubts about tasks (make sure everything is written where you can later reference).
  • Ask the project manager in case something is not clear.
  • Make sure you inform the manager when you are close to becoming idle.

Config project files

  • Create a Last Pass Secure note with your .env file.
  • Add a link to your Last Pass note to Trello’s documents column.

Production and Staging services

  • ALWAYS have Sentry configured and with correct e-mails to project developers.
  • Setup alerts and health checks for critical parts of the project:
    • Setup the following Papertrail alerts:
      • Web errors: "app/web" Internal Server Error
      • Worker errors: "app/worker" ERROR/
      • Platform errors: "error code=H" OR "Error R" OR "Error L"
    • Setup a Librato alert for slow response time.
    • Setup a Uptime Robot alert for uptime.

Feature implementation

Once allocated to a feature, the developer should follow the Feature development workflow, which includes using git-flow and satisfying the PR workflow.

Code and feature review

All code is reviewed before being merged to master. The reviewer not only checks code quality, but also if the feature was implemented according to what the client expects. It's very important for the allocated reviewer to strictly follow the PR review workflow.

Back to the Playbook

We’d love to work with you.

We've worked with a rich variety of clients. Building from simple to complex architectures. Each one with its own problems and challenges.

Let's Build Something Together

Do you need more information about Vinta?

Please contact us at: contact@vinta.com.br and follow us on Twitter.

This work is licensed under a Creative Commons License.Creative Commons License