Skip to main content

Engineering Playbook

Why Have A Playbook​

  • To increase overall efficiency for team members and the whole team in general.
  • To reduce the number of mistakes and avoid common pitfalls.
  • To strive to be better engineers and learn from other people's shared experiences.

Checklist​

This checklist helps to ensure that our projects meet our Engineering Fundamentals.

Source Control​

  • ✅ The default target branch is locked.
  • ✅ Merges are done through PRs.
  • ✅ PRs reference related work items.
  • ✅ PRs must be approved before they can be merged. A required number of approvals are configured. Code Owners are configured.
  • ✅ PRs could be merged only if the pipeline is green.
  • ✅ PRs could be merged only if all threads are resolved.
  • ✅ The project labels are configured and documented. PRs should be labeled.
  • ✅ Delete the source branch on merge by default.
  • ✅ Commit history is consistent and commit messages are informative (what, why). Commitlint is configured.
  • ✅ The Changelog structure is documented and Changelog updating is a part of PR / Release work.
  • ✅ Consistent branch naming conventions are configured.
  • ✅ Clear documentation of repository structure.
  • ✅ Documented links to all the eternal project resources (e.g. Jira, Notion)
  • ✅ The branching strategy is defined and documented.
  • ✅ Clear documentation of tech stack.
  • ✅ The naming convention is documented.
  • ✅ Secrets are not part of the commit history or made public.
  • ✅ For public repositories, the default branch should contain the following files: Description, README, Code of conduct, Contributing, License, Security policy, Issue templates, Pull request template
  • ✅ The policy over generated code by AI is documented.
  • ✅ NPM dependencies have strictly specified versions.

Testing​

  • ✅ The Testing Trophy is documented.
  • ✅ Test Desiderata is documented.
  • ✅ TDD approach is well described.
  • ✅ The Testing Conventions are documented.
  • ✅ The Testing Strategy is documented.
  • ✅ MR checklist contains a point about the required tests adding/updating.
  • ✅ Impact Analyses is documented.

CI/CD​

  • ✅ Dependabot is configured.
  • ✅ Danger is configured.
  • ✅ All the tests are automated.
  • ✅ Code coverage reports are configured and automated.
  • ✅ Code quality Linters and Prettier are configured and automated.
  • ✅ Linters for markdown are configured and automated: markdownlint, github-action-markdown-link-check, write-good
  • ✅ All the builds and deploys are configured and automated.
  • ✅ Bundle-size analyzers are configured and automated.
  • ✅ Copy-Paste analyzer is configured and automated.
  • ✅ commitlint is configured and automated.
  • ✅ The release strategy is documented and automated.
  • ✅ The Changelog generation is generated or checked in the CI.

Security​

  • ✅ Access is only granted on an as-needed basis
  • ✅ Secrets are stored in secured locations and not checked into code
  • ✅ Data is encrypted in transit (and if necessary at rest) and passwords are hashed
  • ✅ Is the system split into logical segments with a separation of concerns? This helps limit security vulnerabilities.

Quick References

Observability​

  • ✅ Significant business and functional events are tracked and related metrics are collected.
  • ✅ Application faults and errors are logged.
  • ✅ The health of the system is monitored.
  • ✅ The client and server-side observability data can be differentiated.
  • ✅ Logging configuration can be modified without code changes (eg: verbose mode).
  • ✅ Incoming tracing context is propagated to allow for production issue debugging purposes.
  • ✅ GDPR compliance is ensured regarding PII (Personally Identifiable Information).

Agile/Scrum​

  • ✅ Process Lead (fixed/rotating) runs the daily standup
  • ✅ The agile process is clearly defined within the team.
  • ✅ The Dev Lead (+ PO/Others) is responsible for backlog management and refinement.
  • ✅ Team Agreements are documented.
  • ✅ A working agreement is established between team members and customers.
  • ✅ The delay in managerial decision-making issue is described to all the team members.
  • ✅ Critical chain conception is described and documented.

Retrospectives​

  • ✅ Retrospectives are conducted each week/at the end of each sprint.
  • ✅ The team identifies 1-3 proposed experiments to try each week/sprint to improve the process.
  • ✅ Experiments have owners and are added to the project backlog.
  • ✅ The team conducts longer retrospectives for Milestones and project completion.

Design Reviews​

  • ✅ The process for conducting design reviews is included in the Working Agreement.
  • ✅ Design reviews for each major component of the solution are carried out and documented, including alternatives.
  • ✅ Stories and/or PRs link to the design document.
  • ✅ Each user story includes a task for design review by default, which is assigned or removed during sprint planning.
  • ✅ Project advisors are invited to design reviews or asked to give feedback on the design decisions captured in the documentation.
  • ✅ Discover all the reviews that the customer's processes require and plan for them.
  • ✅ Clear non-functional requirements captured.

Code Reviews​

  • ✅ There is a clear agreement in the team as to the function of code reviews.
  • ✅ The team has a code review checklist or established process.
  • ✅ A minimum number of reviewers (usually 2) for a PR merge is enforced by policy.
  • ✅ Linters/Code Analyzers, tests and successful builds for PR merges are set up.
  • ✅ The code review deadlines are described
  • ✅ The code review exceptions handling is described
  • ✅ The required number of reviewers is described
  • ✅ There is a process to enforce a quick review turnaround.

Developer Experience (DevEx)​

  • ✅ The list of recommended software is provided.

Rush.js and PNPM monorepository​

  • ✅ The package manager is pnpm.
  • ✅ pnpm workspaces are enabled.
  • ✅ All the duplicated configs are moved to separate packages.
  • ✅ repository.url is set in the rush.json.
  • ✅ ensureConsistentVersions is set to true in the rush.json.
  • ✅ strictPeerDependencies is set to true in the pnpm-config.json
  • ✅ The build cache is enabled and configured.
  • ✅ Command and scripts are configured through the command-line.json and autoinstallers (if relevant).