@qiwi/tech-radar
v1.13.19
Published
Fully automated tech-radar generator
Downloads
197
Readme
📡 QIWI • Android • Backend • iOS • ISEC • JS • OPS • QA
Fully automated tech-radar generator. Based on zalando/tech-radar. Boosted with 11ty
Purpose
The Tech Radar is a tool to inspire and support engineering teams at Zalando to pick the best technologies for new projects; it provides a platform to share knowledge and experience in technologies, to reflect on technology decisions and continuously evolve our technology landscape. Based on the pioneering work of ThoughtWorks, our Tech Radar sets out the changes in technologies that are interesting in software development — changes that we think our engineering teams should pay attention to and consider using in their projects.
We've just slightly modified the original implementation for our bloody enterprise requirements.
Table of contents
Key features
- Builds radars by
csv
,json
oryaml
data - Renders a separate description page for each radar entry
- Compares radars of the same scope with each other and shows the movement of points
- Assembles all the radars refs on the main navigation page
- Redirects scope urls to the latest version of their radars
- CLI / JS / TS API
Requirements
- Node.js >= 14.13
- macOS / linux
Install
# yarn
yarn add @qiwi/tech-radar
# npm
npm i @qiwi/tech-radar
Usage
CLI
# via local dep
techradar --input "/path/to/files/*.{json, csv, yml}" --output /radar
# through npx
npx @qiwi/tech-radar --input "/path/to/files/*.{json, csv, yml}" --output /radar
| Option | Description | Default |
|-------------|-------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------|
| cwd | Current working dir | process.cwd()
|
| input | glob pattern to find radar data: csv/json/yml | <cwd>/data/**/*.{json,csv,yml}
|
| output | Output directory | <cwd>/radar
|
| autoscope | identify same-scoped files as subversions of a single radar | false
|
| base-prefix | base context path for web statics | tech-radar
|
| nav-page | create navigation page | false
|
| nav-title | navigation page title | 📡 Tech radars
|
| nav-footer | navigation page footer | |
| temp | temporary assets dir | tempy.directory()
|
| templates | custom 11ty/nunjucks
compatible templates directory. Its contents will be merged into the default templates dir |
JS API
import {run} from '@qiwi/tech-radar'
await run({
input : 'data/*.{csv,json,yml}',
output : 'dist',
basePrefix: 'your project',
autoscope: false
})
Input examples
{
"meta":{
"title": "tech radar js",
"date": "2021-06-12"
},
"data":[
{
"name": "TypeScript",
"quadrant": "languages-and-frameworks",
"ring": "Adopt",
"description": "Статически типизированный ЖС",
"moved": "1"
},
{
"name": "Nodejs",
"quadrant": "Platforms",
"ring": "Adopt",
"description": "",
"moved": ""
},
{
"name": "codeclimate",
"quadrant": "tools",
"ring": "Trial",
"description": "Статический анализатор кода",
"moved": "0"
},
{
"name": "Гексагональная архитектура",
"quadrant": "Techniques",
"ring": "Assess",
"description": "Унификации контракта интерфейсов различных слоев приложений",
"moved": "-1"
}
],
"quadrantAliases": {
"q1": "languages-and-frameworks",
"q2": "platforms",
"q3": "tools",
"q4": "techniques"
},
"quadrantTitles": {
"q1": "Languages and frameworks",
"q2": "Platforms",
"q3": "Tools",
"q4" :"Techniques"
}
}
meta:
title: tech radar js
date: "2021-06-11"
data:
-
name: TypeScript
quadrant: languages-and-frameworks
ring: Adopt
description: Статически типизированный ЖС
moved: 1
-
name: Nodejs
quadrant: Platforms
ring: Adopt
description:
moved:
-
name: codeclimate
quadrant: tools
ring: Trial
description: Статический анализатор кода
moved: 0
-
name: Гексагональная архитектура
quadrant: Techniques
ring: Assess
description: Унификации контракта интерфейсов различных слоев приложений
moved: -1
quadrantAliases:
q1:
- languages-and-frameworks
- lnf
- lang
- framework
q2: platforms
q3: tools
q4: techniques
quadrantTitles:
q1: Languages and frameworks
q2: Platforms
q3: Tools
q4: Techniques
title
tech radar js
===
date
2021-06-18
===
name, quadrant, ring, description, moved
TypeScript, language, Adopt, "Статически, типизированный ЖС", 1
Nodejs, Platforms, Adopt, ,
codeclimate, tools, Trial, Статический анализатор кода, 0
Гексагональная архитектура, Techniques, Assess, Унификации контракта интерфейсов различных слоев приложений, -1
===
quadrant, alias
q1, language
q1, Languages-and-frameworks
q2, Platforms
q3, Tools
q4, Techniques
===
quadrant, title
q1, Languages and frameworks
q2, Platforms
q3, Tools
q4, Techniques
CI/CD
Follow gh-action usage example:
release_radar:
name: Publish radar to gh-pages
# https://github.community/t/trigger-job-on-tag-push-only/18076
if: github.event_name == 'push' && github.ref == 'refs/heads/master'
runs-on: ubuntu-latest
needs: test
steps:
- name: Checkuout
uses: actions/checkout@v2
- name: Setup NodeJS
uses: actions/setup-node@v2
with:
node-version: 16
- name: Install deps
run: yarn
- name: Generate
run: yarn generate
- name: Publish gh-pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./dist
commit_message: "docs: update tech-radar static"
allow_empty_commit: true
enable_jekyll: false
"scripts": {
"generate": "node ./src/main/js/cli.mjs --input \"data/**/*.{csv,json,yml}\" --output dist --base-prefix tech-radar --autoscope true --nav-page true && touch dist/.nojekyll"
},
Customization
Group labels
Every radar document provides its own definition of what each quadrant
does represent. Change if necessary.
quadrant, title
q1, Languages and frameworks
q2, Platforms
q3, Tools
q4, Techniques
Ring colors
The easiest way to tweak up the look of your radar is by adding an alternative color scheme. renderSettings
option is exactly for that:
{
"svg_id": "radar",
"width": 1450,
"height": 1100,
"colors": {
"background": "#fff",
"grid": "#bbb",
"inactive": "#ddd"
},
"rings": [
{ "name": "ADOPT", "color": "#93c47d", "id": "adopt" },
{ "name": "TRIAL", "color": "#93d2c2", "id": "trial" },
{ "name": "ASSESS", "color": "#fbdb84", "id": "assess" },
{ "name": "HOLD", "color": "#efafa9", "id": "hold" }
],
"print_layout": true
}
Templates
For advanced view modification, you can use your own templates. Pass template
option to navigate the dir, where your own custom .njk
files are placed. Expected structure:
assets
favicon.ico
radar.css
radar.js
_data/
settings.json
_includes
footer.njk
_layouts
entries.njk
page.njk
radar.njk
redirect.njk
root.njk
Contributing
Feel free to open new issues: bug reports, feature requests or questions. You're always welcome to suggest a PR. Just fork this repo, write some code, add some tests and push your changes. Any feedback is appreciated.
Update the radar data
- Clone the repo:
git clone [email protected]:qiwi/tech-radar.git
- Install deps:
yarn install
- Place a new radar data file to
data/<scope>/<date>.{csv|json|yaml}
- Fill it as shown in examples / its siblings
- Run
yarn generate && yarn preview
- Follow http://localhost:3000/. Assess the result
- Push commit and create a pull request
Enhance the generator
- Clone the repo:
git clone [email protected]:qiwi/tech-radar.git
- Install deps:
yarn install
- Make some changes in
src/main/js
- Put some tests to
src/test/js
- Run
yarn test
- Repeat if necessary steps 1 to 3
- Push commit and create a pull request
Alternatives
- https://github.com/thoughtworks/build-your-own-radar
- https://github.com/zalando/tech-radar
- https://www.npmjs.com/package/@backstage/plugin-tech-radar