Welcome to Engineering Standards

This document defines how to write code that is suitable for production use.

This document discuss the following engineering Standards:

• Code Quality
• 12 factor app https://12factor.net/
• owasp coding practices https://owasp.org/www-pdf-archive/OWASP_SCP_Quick_Reference_Guide_v2.pdf (security)

Code Quality

Github Workflow

GitHub flow is a lightweight, branch-based workflow that supports teams and projects where deployments are made regularly. This guide explains how and why GitHub flow works.

1. Create a branch
2. Add a commit
3. Open a PR/MR
4. Review Code
5. Merge
6. Deploy

Reference:

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

Linting

A linting tool (linter) is a tool that programmatically scans your code to find any suspicious constructs and bugs. that might cause issues when the application runs.

Interpreted Programming Languages Like Python and Javascript benefits greatly from linters as there is no compilation phase to detect suspicious code.

A linter also could use to style and format your code to specific coding style guidance you specify to it.

example of linters for python:

• flake8
• pylint

example of the usage of linter on winterlight: https://code.roche.com/ace/winterlight/-/merge_requests/9

Testing and Coverage

Automated Testing is a software technique that performs some steps to ensure that your functions does what it is supposed to do.

Creating test cases for the most important pieces of code with different inputs to make sure that the actual output is the same as the expected actual is really encouraged.

Test Coverage is basically a code analysis technique that runs the test cases and see which lines of code has been executed and tested. coverage basically creates reports on how much of the code has been tested and which parts are tested and which parts are not tested

example of Testing tools for python:

• pytest
• PyUnit

example of coverate tools for python:

• coverage.py
• codecov

example of testing and coverage usage on winterlight: https://code.roche.com/ace/winterlight/-/merge_requests/10

Healthchecks for APIs

Sometimes APIs can be incapable of serving requests but it is still running and not showing any issues.

To Identify these issues and to recover from it. an Health Checks API should be implemented in APIs.

These APIs are used by a higher level application to determine the state of the application and the API to figure out if it is actually serving requests or it is running doing nothing.

These higher level applications (e.g. kubernetes) just ping the health check endpoint each interval and if it failed more than certain number of threshold it restarts the process (How many failed request and hit health check endpoint interval is configurable).

Example of healthchecks in winterlight: https://code.roche.com/ace/winterlight/-/merge_requests/8

Reference:

• https://microservices.io/patterns/observability/health-check-api.html

Semantic Release

semantic-release automates the whole package release workflow including: determining the next version number, generating the release notes and publishing the package.

Semantic release is enabled by conventional commits which is conventional on how to write consistent human readable commits and these conventional commits will help semantic release to determine how to pop up semantic version.

• fix: a commit of the type fix patches a bug in your codebase (this correlates with PATCH in Semantic Versioning).
• feat: a commit of the type feat introduces a new feature to the codebase (this correlates with MINOR in Semantic Versioning).
• BREAKING CHANGE: a commit that has a footer BREAKING CHANGE:, or appends a ! after the type/scope, introduces a breaking API change (correlating with MAJOR in Semantic Versioning). A BREAKING CHANGE can be part of commits of any type.

Example of Semantic Release in winterlight: https://code.roche.com/ace/winterlight/-/merge_requests/5/diffs

References:

• https://github.com/relekang/python-semantic-release
• https://github.com/semantic-release/semantic-release
• https://semver.org/

Logging

Logging is presenting the events that the application has taken to perform a function.

Logging is important because since the application is deployed into production if there is no logs, noone will have any visibility which events the application has taken and if these steps are going as planned and coded.

Logging help the developers and the operations team debug the application easily if there is any bug introduced or any crashes happened to the application.

Logs is one of telemetry types that help of in the observability of the application. other telemetry types are metrics and traces

Example of logging in winterlight: https://code.roche.com/ace/winterlight/-/merge_requests/12

Dependencies management

For dependencies management I would to introduce a tool called poetry , it allows you to declare the dependencies your project depends on.

poetry uses pyproject.toml to replace setup.py, requirements.txt, setup.cfg, MANIFEST.in and the newly added Pipfile.

other benefits:

• It will try to enforce semantic versioning as the best practice in version naming.
• You can specify the readme, included and excluded files: no more MANIFEST.in. poetry will also use VCS ignore files (like .gitignore) to populate the exclude section.
• Keywords (up to 5) can be specified and will act as tags on the packaging site.
• The dependencies sections support caret, tilde, wildcard, inequality and multiple requirements.
• You must specify the python versions for which your package is compatible.

poetry integrates nicely with the semantic release patternn using pyproject.toml. it is similar to npm for NodeJS.

Example of poetry usage in winterlight: https://code.roche.com/ace/winterlight/-/merge_requests/5

Reference: https://github.com/python-poetry/poetry