# Technical Design Reviews at Marfeel
A Technical Design Review is a document Marfeelers need before starting new developments. It highlights the problems the new feature will solve, and weigh the different technical solutions. Everybody at Marfeel is welcome to comment on a TDR, to add concerns or propose different approaches that are not mentioned yet.
Writing TDRs allows Marfeel to be:
- Ahead of issues: New developments consider long term implications, and not only one tenant's issue.
- Open to contribution: All interested marfeelers can contribute to architectural changes.
- Business-friendly: Refactors are "sponsored" by the new feature they support.
- User-centric: Users (eg. GOL teams for inventory features) can voice their needs and concerns before development starts.
# When to write a TDR
It is mandatory to write a TDR in the following cases:
- When the stakeholder and owner teams are different.
- i.e. Solutions submits a request for improvement on AdDealer to ALOT
- When an owner team changes services that may affect external stakeholders
- i.e. changes on Boiler done by Rocks can affect Solutions
- When the development may affect different building blocks of the architecture
- i.e. Systems working on the new M-Shield
# Where to write a TDR
TDRs can be either in an existing code repository, or inside the Tech Council repository.
In an existing code repository, TDRs should all be grouped in a specific folder, tdr. This folder follows the same rules as the docs folder: it is at the root of the repository for microservices, and in the appropriate module for monorepos.
# Existing code repository
TDRs that are about an existing project should be written inside that project's repository.
Examples:
- Section pagination in Gutenberg
- Puppeteer in Gutenberg
- Ad server providers in MarfeelXP
# Tech Council repository
TDRs that are about new projects, that don't already have an appropriate code repository, should be written in the Tech Council repository.
TDRs that are about sensitive Marfeel features, which should not be made public to all marfeelers until a decision is taken, should be written in the Tech Council repository.
This repository has limited access across Marfeel. Once the feature is under development, the TDR can be moved to the appropriate repository.
# How to ask for contributions
A TDR is not useful if only you work on it, it must be shared.
Once the first version of the TDR is written, and a pull request is open, it's time to tell marfeelers.
You can send an email to tech@marfeel.com asking for comments, including the link to the TDR pull request.
At a minimum, CC the email to the specific persons or teams you need to review the TDR and assign them as reviewers to the pull request.
Your reviewers can be chosen for different reasons:
- Previous knowledge of the code that is going to be changed,
- The person is a stakeholder or has a special interest in the feature,
- ...
The TDR meeting must only be attended by those who:
- have made contributed to the TDR
- have left comments in the TDR pull request
- are stakeholders
- have a special interest in the feature
TIP
Include a link to the pull request in the TDR itself, so that future marfeelers can easily access all the past discussions.
# How to contribute
TDRs are part of Marfeel source code, which means they follow its git-centric flow. Write all your contributions as comments on the open pull request with the TDR: this guarantees traceability for all the decisions taken during the design phase.
WARNING
The TDR stays in PR while gathering feedback, so anyone can comment on it.
Feel free to plan a meeting with the TDR author if your concerns are important.
# How to finalize a TDR
The TDR team should present it to the product council.
A TDR is finalized when:
- The final scope and tech design are decided based on all known trade-offs
- The spikes required before development are identified and evaluated
The Pull Request containing the TDR can be merged once approved by the product council. Failing that, the TDR must be approved by the related project's codeowners.