Style Guides

Development principles

  • Zen of Python.
  • 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. Separation of Concern vs Single Responsibility Principle.
  • 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. See this interesting HN discussion.
  • 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.
  • Write code that is easy to delete, not easy to extend Things change in unexpected ways.
  • Feature Toggles (aka Feature Flags). 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.



  • 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 (keep them in an untracked .env or .ini file so they are not pushed to the repository). 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(s) responsible).

Server access information

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

Config project files

  • Create a Last Pass Secure note with your .env file.

Production and Staging services

Libs and Tools we use

We use several open source projects as part of our tech stacks - both on backend (Python) and frontend (JavaScript/React).

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.


Security is no easy topic to talk about. There are many ways to explore vulnerabilities in a website, as well as security implications for day-to-day practices and processes. To address that we follow security guidelines and use well known and tested tools to reduce risks. Although writing code that is robust and tested against vulnerabilities is essential for secure applications, it's well known that social engineering is many times the weakest link in the chain. For that, we enforce tools and practices that tackle this kind of problem. Below are our processes for reducing security-related risks:

Employees and Accounts

  • 2-factor authentication everywhere it's possible (enforced to everyone on our organization accounts on GitHub, Google G Suite, etc)
  • Email managed by Google G Suite
  • LastPass managed passwords for all shared accounts
  • Encrypted disks on all computers
  • Invalidation of all accounts and keys when a employee leaves the company
  • No reuse of email addresses of employees that left the company
  • Deletion of all code and assets after we leave a project

Code Security

  • Static analysis with dodgy (to avoid secret keys on code) and bandit (to avoid common vulnerabilities), configured both in CI and pre-commit hooks.
  • Dependency insecure version management with safety (on CI) and GitHub Security Alerts
  • Critical flows review checklists during code review and QA

Application Security

  • Sqreen
  • Launch checklist that we run periodically, to check things like Django settings, oAuth keys rotations, SSL health, etc.
  • Unprivileged run (we mostly use PaaS like Heroku)
  • Avoiding downloads of production data, and if it's needed, it must be anonimyzed before download
  • Exception monitoring with Sentry

Encrypting Sensitive Messages

Every once in a while it's necessary to transfer security sensitive information such as passwords to clients. Use GPG to encrypt that kind of information

Additional resources

Checklist index

Agile Process Guidelines

"Artists know that there is no creativity without a system of formal restraints." What Kathy Galloway said also applies to projects, the best and most creative work comes from a set of refrains that doesn’t choke anyone and guides them to a better result. Here are ours.

Methodology overview

Vinta works following an Agile-like methodology:

  • Sprints, two-weeks long. Sprints are a lightweight process aligned to "Responding to change over following a plan".
  • Use of Asana as the main management tool. There we align expectations, because we want "Customer collaboration over contract negotiation".
  • Use of GitHub for Git repository hosting and code review, along with a continuous integration tool, like CircleCI or Travis CI, so we ensure "Working software over comprehensive documentation".
  • Use of Slack for real-time communication, since we consider "Individuals and interactions over processes and tools".

Product Managers duties

Usually, the product manager role is filled by someone on the client's side. These are our expectations:

  • Keep the business and the development team closer.
    • Communicate strategic decisions to the development team and help it to update priorities accordingly.
  • Be responsible for the product's decisions making, asking for advice when necessary.
    • Produce feedback for UI/UX deliverables. Also accepting input from the design team.
  • Be responsible for communication with the technical team.
  • Produce insights for mid and long-term product strategy (quarter-based).
    • By getting inputs from all stakeholders, including the development/design team.
    • By analyzing risks and tradeoffs.
  • Keep Roadmap updated considering technical challenges and product strategy.
    • Together with the development team.
    • Warn team about changes ASAP to avoid development work loss.
  • Be aware of the development team needs, such as new developers, designers, QAs, etc.
  • Planning and syncing project major releases among development and business teams.
  • Provide and analyze metrics and data from development team aiming to support product strategy.
  • Validate technical team decisions that impact product strategy.
  • Find, analyze, and sync strategic partners.
  • Analyze regularly competitors features/flows.

Project Managers duties

  • A Project Manager's most important duty is to manage client's expectations and keep them realistic. We realize most of the problems in software development come from communication issues, and the Project Manager at Vinta is the 'Communication Person'. The Project Manager should always track the deliverables for the next sprint and, if any problems are to appear, features must be simplified, development strategies re-evaluated, and priorities re-defined, always sided with the client. That's easier said than done in some cases, but surely brings benefits for us and the clients.
  • The Project Manager will be the main point of contact with the client. It's good for everyone to have an open communication channel directly with the client, but the Project Manager should be aware of all project-related decisions. However, regarding assigned tasks, each developer is free to discuss and validate it directly with the client. Should the client ask the developer to do another task, this needs to be tracked and communicated to the Project Manager. Maybe the manager knows better the priority, even better than the client, so s/he needs to step in.
  • Project Manager will work on the project as a developer too.
  • Project Manager should encourage everyone to manually test all features before validating them with the client.
  • Project Manager should remember developers to report daily on what they are working on.
  • Project Manager should alert everyone to turn off Slack "do not disturb" option so the client can reach them in case of emergencies.
  • Project Manager should make sure there are no ownership gaps in the project. When everybody is responsible for some parts of the process, there might be gaps where no one acts. The project manager must be aware of those gaps and address them with the team. Critical aspects of the project such as support, deploys, QA, security, etc must have a person clearly responsible. Project Manager should also inform the client who's responsible for each aspect. This kind of ownership gives team members responsibility and autonomy.
  • Project Manager should ensure the project's documentation is up-to-date and make sure it's shared with the Client.

Daily Attributions

  • Make sure process is being followed by everyone in the team: code is being reviewed, tests are being written, ...
  • Assert team is writing quality code.
  • Guarantee technical debt is not being overlooked and allocate accordingly when payment is urgent. Be emphatic when needed about this with the client.
  • Advise less experienced team members.
  • Watch for tools and processes that can improve the team's and project's wellness and performance.
  • Create a healthy environment for people to grow. This includes making sure everyone: has active voice in decisions and feels safe to ask, learn and give opinions.
  • Guide the team towards the best decisions.
  • Be tough when the team is heading in the wrong direction. When the team lacks consensus or when it feels appropriate, PM will have the final say.
  • Delegate and trust the team to execute any kind of job. There's no such thing as a task that can only be performed by a PM.

Not team lead attributions:

  • Review every single piece of code.
  • QA every single functionality.
  • Solely assume responsibility during crisis.
  • Micromanage people's work.




Read Development section to understand how features should be implemented and what are the coding guidelines.


The retrospective is the moment to evaluate the work that was done on the previous sprint(s). Every person must think on their own and collaborate with the team to propose solutions. There's no right answer as to how often retrospectives should happen, they can be weekly, biweekly, monthly. The periodicity depends on the team's needs.

There are different techniques that can be used such as Daki Exercise, Stop, Start, Continue, etc. However, the general idea is to have a clear vision of:

  • What the team learned
  • What was good
  • What was bad
  • What can improve


It is proven that a high deploy frequency is a good DevOps practice and improves productivity of Agile teams. Google considers multiple deploys per day as a factor to consider a team as an Elite Performer.

Deploying more frequently:

  • Represents having smaller changes, which means less risk.
  • Decreases the time between a feature being ready and being live.
  • Encourages better feature QA, since features will spend less time on Staging until they launch to Production.
  • Increases code review quality, since changes tend to be smaller.
  • Incentivizes breaking up bigger tasks in smaller ones that can be deployed as soon as they are ready.
  • Facilitates bugs detection.
  • Means less pressure on the team, regarding deadlines. The team might feel pressured to rush development or QA to meet deadlines if the deploy granularity is too low and the gap between ready and live is bigger. For instance, in Weekly Deploys, an one day delay means that the change won't be live for another week. That problem is mitigated if there were Daily Deploys.

Visit our Daily Deploy Checklist, that describes a process for Daily Deployment at Vinta.

Good Practices

  • Encourage the team to track topics they want to discuss at retrospectives.
  • During the retrospective, take notes to keep track of feedbacks and goals defined.
  • Open past notes and discuss how every feedback from the last retrospective was addressed.
  • Brainstorm and discuss new inputs for each topic. But keep discussions objective.
  • Don't sink into unnecessarily long dialogs. Some teams adopt a limited time frame.
  • Try to keep discussions about processes. Avoid long technical discussions.
  • Make sure topics discussed translates to actions.

DAKI Exercise

  • D for Drop: When team members want to drop or remove something that bothers them. For example, a team wants to remove (drop) weekly meeting with their manager because of micromanaging.
  • A for Add: What does the team want to add to improve the process? Perhaps adding a weekly breakfast for the whole team or a company to share feelings/feedback with the rest of the people.
  • K for Keep: When team members want to keep something. For example, the team decides to keep a stand up meeting with a song chosen by a team member.
  • I for Improve: Something that a team wants to improve. A good example is when a team reduces the technical debt from a legacy code to avoid fixing bugs all day long.