diff --git a/README.md b/README.md index 9126a6c..b7d8a85 100644 --- a/README.md +++ b/README.md @@ -1,73 +1,133 @@ # AOE Technology Radar + A static site generator for AOE Technology Radar -## Looking for the AOE Tech Radar content? -The repository is now found here: https://github.com/AOEpeople/techradar +![Screenshot of the AOE Technology Radar](./docs/assets/screenshot-techradar.png) -The AOE Tech radar is deployed here: https://www.aoe.com/techradar/index.html +## Looking for the AOE Tech Radar content? + +- The repository is now found here: https://github.com/AOEpeople/techradar +- The AOE Tech radar is deployed here: https://www.aoe.com/techradar/index.html + +## ✨ Version 4.0.0 + +Version 4.0.0 is a complete rewrite of the AOE Technology Radar. It is now based +on [Next.js](https://nextjs.org/) to provide enhanced static site generation. The visualization has +been rewritten without the need for the D3 dependency. New features include a fuzzy search based on +Fuse.js, non-overlapping blips on the radar, and a reworked tag filter on the homepage. + +To migrate from the old version please migrate your `package.json`'s scripts and create a +new `config.json` based on the documentation below. You can find a reference implementation in +our [repo](https://github.com/AOEpeople/techradar). The old version is still available in the `v3` +branch. ## Create your own radar -The generator is free to use under Open Source License - in fact there are already some other Radars published based on our Radar and there are also Contributions back. -However, please be aware: +The generator is free to use under Open Source License - in fact there are already some other Radars +published based on our Radar and there are also Contributions back. However, it would be nice to +mention in radar that the generator is based on this repository. -- It would be nice to mention in radar that the generator is based on this repository. -- Also, when you want to reuse the CSS and Styling: Change the font (it is a licensed font) and the colors (It using AOE CI) +### Step 1: Create a new project -### Use and build the radar -Create a new npm project and add the tech radar as a dependency -``` -npm i aoe_technology_radar +Create a new npm project by creating a new folder with a `package.json` file like the following and +adapt to your +needs: + +```json +{ + "name": "aoe-techradar", + "version": "1.0.0", + "license": "MIT", + "scripts": { + "build": "techradar build", + "serve": "techradar serve" + }, + "dependencies": { + "aoe_technology_radar": "^4" + } +} ``` -Build the radar -``` -npx aoe_technology_radar-buildRadar -``` +Run `npm install` to install the dependencies -Generate the `rd.json` file containing the radar data -``` -npx aoe_technology_radar-generateJson -``` +### Step 2: Change logo and the favicon -Run the Prepare script -``` -npm run prepare -``` +Create a folder named `public` and put your `logo.svg` and `favicon.ico` in it. +For reference have a look at [public/logo.svg](./public/logo.svg). -Serve -``` -cd build -python3 -m http.server 8080 -``` +### Step 3: Configure the radar -Then open here: http://localhost:8080/ +Copy the [`config.json`](./data/config.json) next to the `package.json` and adapt it to your needs. -### Run a prepared static version +| Attribute | Description | +| --------- | --------------------------------------------------------------------------------- | +| basePath | Set if hosting under a sub-path, otherwise set it to `/`. Default is `/techradar` | +| colors | A map of colors for the radar. Can be any valid CSS color value | +| quadrants | Config of the 4 quadrants of the radar. See config below. | +| rings | Config of the rings of the radar. See config below. | +| flags | Config of the flags of the radar. See config below | +| chart | If you hava a lot of items, you can increase the `size` to scale down the radar | +| social | Social links in the footer. See config below | +| imprint | URL to the legal information | +| labels | Configure the labels to change the texts and labels of the radar | -To have a better SEO ranking or deploy to S3, you can generate a html file for every page. +#### `config.quadrants` -Requirements -* Build the radar -* Generate the `rd.json` file +| Attribute | Description | +| ----------- | ----------------------------------------------------------- | +| id | Used as reference in the radar markdown files and URLs | +| title | Title of the quadrant | +| description | Will be shown on startpage and on the quadrants detail page | +| color | Color of the quadrant arcs and blips | -``` -npx aoe_technology_radar-createStaticFiles -``` +#### `config.rings` -## Authoring Techradar contents -For a new Technology Radar release, create a folder of the release date (YYYY-MM-DD) under `./radar`. +| Attribute | Description | +| ----------- | --------------------------------------------------------------------------- | +| id | Used as reference in the radar markdown files | +| title | Title of the ring. Will be used in the badge | +| description | | +| color | Color of the ring's badge | +| radius | Size of the ring. Value between 0 and 1, where 0.5 would be a ring 50% wide | +| strokeWidth | Size of the ring's border | + +#### `config.flags.[new|changed|default]` + +| Attribute | Description | +| ----------- | ------------------------------------------ | +| color | Color of the flag | +| title | Long label of the flag | +| titleShort | Short label (single letter) shown in lists | +| description | Label in the radar legend | + +#### `config.social.[]` + +| Attribute | Description | +| --------- | ---------------------------------------------------------------------------- | +| href | URL to the website | +| icon | One of `facebook`, `github`, `instagram`, `linkedin`, `x`, `xing`, `youtube` | + +### Step 4: Add a help page with explanations + +Create a file `about.md` next to the `package.json` file. This file will be shown on +the `/help-and-about-tech-radar` page. Optionally you can change the title of the menu by +setting `labels.pageAbout` in your `config.json`. + +### Step 5: Create the radar items + +For a new Technology Radar release, create a folder of the release date (YYYY-MM-DD) +under `./radar`. e.g. `./radar/2024-03-01`. -### Maintaining items The items are written in Markdown format (.md) -Each file has a [front-matter](https://github.com/jxson/front-matter) header where the attributes of the item are listed: +Each file has a meta header where the attributes of the item are listed: ``` --- -title: "React" -ring: adopt -quadrant: languages-and-frameworks +title: "React" +ring: adopt +quadrant: languages-and-frameworks +tags: [frontend, coding] --- Text goes here. You can use **markdown** here. @@ -76,11 +136,9 @@ Text goes here. You can use **markdown** here. Following front-matter attributes are possible: - **title**: Name of the Item -- **quadrant**: Quadrant. One of `languages-and-frameworks`, - `methods-and-patterns`, `platforms-and-aoe-services`, `tools` -- **ring**: Ring section in radar. One of `trial`, `assess`, `adopt`, `hold` -- **info**: (optional) A short textual description of the item (visible in - overview pages) +- **quadrant**: Quadrant. One of the configured quadrants in `config.quadrants` +- **ring**: Ring section in radar. One of the configured rings in `config.rings` +- **tags**: Optional tags for filtering. - **featured**: (optional, default "true") If you set this to `false`, the item will not be visible in the radar quadrants but still be available in the overview. @@ -90,261 +148,38 @@ the same name from older releases. If an item is overwritten in a new release, the attributes from the new item are merged with the old ones, and a new history entry is created for that item. -You can integrate images in your markdown. Put the image files in your public folder and reference them +You can integrate images in your markdown. Put the image files in the `public/images` folder and +reference them ``` -![nice image](/images/nice-image.png) +![nice image](/images/optional-content-image.png) ``` -## Customize the tech radar -You can customize the following parts of the tech radar. +### Step 6: Build your radar -### Change title, description and headline -Set the environment variable `REACT_APP_RADAR_NAME`. The default is "AOE Technology Radar". +Your final file and folder structure should look like this: -Set the environment variable `REACT_APP_RADAR_TITLE_FORMAT` to define the title format for each technology page. -You can use two placeholders here: - -- `%TECHNOLOGY_NAME%`: The name of the technology will be inserted -- `%APP_TITLE%`: The base app name (from `REACT_APP_RADAR_NAME`) will be inserted - -For example: `%TECHNOLOGY_NAME% | %APP_TITLE%` - -### Host the application under a sub path -To host the application under a sub path, set the environment variable `PUBLIC_URL`, e.g. "/techradar". The default is "/". - -### Change the favicon -To change the favicon, create a folder named `public` and put your `favicon.ico` in it. - -### Change the logo -To change the logo, create a folder named `public` and put your `logo.svg` in it. - -For reference have a look at [public/logo.svg](./public/logo.svg). - -### Change the date format -By default the Date format used in the app is `"MMMM YYYY"`. -You can change this by editing the `config.js` file as shown below. -Please be sure you are entering a valid [moment.js format string](https://momentjs.com/docs/#/displaying/format). - -```json -{ - // ... - "dateFormat": "MMMM YYYY" -} +``` +├── about.md +├── config.json +├── package.json +├── public/ +│ ├── images/ +│ │ └── optional-content-image.png +│ ├── favicon.ico +│ └── logo.svg +└── radar/ + ├── 2023-12-31/ + │ ├── demo-item-1.md + │ └── demo-item-2.md + └── 2024-03-05/ + ├── demo-item-1.md + └── demo-item-3.md ``` -For reference have a look at [public/logo.svg](./public/logo.svg). +Run `npm run build` to build the radar and +upload the files of the `./build` folder to your server. -### Edit from published radar -You can activate the `editLink` feature which will display a small edit button next to a technology which let's you jump directly to a gitlab / github / etc. edit page: - -```json -{ - // ... - "editLink": { - "radarLink": "https://github.com/AOEpeople/techradar/edit/main/radar", - "title": "Edit" - } -} -``` - -### Change the rings and quadrants config -To change the default rings and quadrants of the radar, you can place a custom `config.json` file within the `public` folder. -The `showEmptyRings` option can be enabled to display the header for a ring even when it contains no items (helpful to -reinforce the order of the rings). -The content should look as follows: - -```json -{ - "quadrants": { - "languages-and-frameworks": "Languages & Frameworks", - "methods-and-patterns": "Methods & Patterns", - "platforms-and-operations": "Platforms & Operations", - "tools": "Tools" - }, - "rings":["all", "adopt", "trial", "assess", "hold"], - "showEmptyRings": true -} -``` - -### Filter with tags / create different Radars -To create different radars with one set of blips put a `tags` entry in your frontmatter: -```yaml ---- -title: Item -ring: adopt -quadrant: tools -tags: [radar-1, radar-2] ---- -``` - -Then, to select the blips put a `tags` entry in the `config.json` for generating the site: -```json -{ - "tags": ["radar-1"], - "quadrants": { - ... -``` - -This will only add blips with the defined tags into the output. - -### Change the index.html -To change the index.html, create a public folder in your application and put your `index.html` in it. - -For reference have a look at [public/index.html](./public/index.html). - -### Change the fonts -To change the fonts, create a public folder in your application and put your fonts in it. - -Create a `fonts.css` in the public folder and load your fonts. -> For now only 2 fonts will be used: `DIN normal` and `DIN 300`. -> Therefore, you only can replace the font files itself, but need to use the font-family and font-weight. -```css -@font-face { - font-family: "DIN"; - src: url("fonts/yourFontFileForNormal"); - font-weight: normal; -} - -@font-face { - font-family: "DIN"; - src: url("fonts/yourFontFileForThin"); - font-weight: 300; -} -``` - -For reference have a look at [public/fonts.css](./public/fonts.css). - -### Change the styles - -To change the styles, create a `styles.css` in the `public` folder and apply your style modifications. -Styles defined in `public/styles.css` will overload the default styles. - -For reference have a look at [src/styles/main.scss](./src/styles/main.scss) and all it's included files. - -> Important: The custom styles must be defined as pure CSS, -> as there is no further pre-processing of other file formats such as SCSS for custom style overloads. - -You can also reference custom icons or images in your styles as follows. -The icons should be placed in the `public` folder as well (e.g. in a specific `icons` or `images` directory): - -```css -body { - background-image: url('/images/my-custom-background-image.png'); -} -``` - -### Add social links to the footer and sidebar -To add social links, create a public folder in your application and put a `messages.json` in it. -```json -{ - "socialLinks": [ - { "href": "https://www.facebook.com/aoepeople", "iconName": "facebook" }, - { "href": "https://twitter.com/aoepeople", "iconName": "twitter" }, - { "href": "https://www.linkedin.com/company/aoe", "iconName": "linkedIn" } - ] -} -``` - -> For more information and the possible icon names see the source code of the [SocialLink Component](./src/components/SocialLink/SocialLink.tsx). - -### Add a legal information link to the footer and sidebar -To add a link to legal information, create a public folder in your application and put a `messages.json` in it. -```json -{ - "legalInformationLink": "https://www.aoe.com/en/imprint.html" -} -``` - -### Add a footnote with the logo to the footer -To add a footnote to the footer, create a public folder in your application and put a `messages.json` in it. -```json -{ - "footerFootnote": "AOE is a leading global provider of services for digital transformation and digital business models. AOE relies exclusively on established Enterprise Open Source technologies. This leads to innovative solutions, digital products and portals in agile software projects, and helps build long-lasting, strategic partnerships with our customers." -} -``` - -> The footnote information may include HTML like `My Link` which will be sanitized. - -### Add a help page with explanations -To add a help page, create a public folder in your application and put a `messages.json` in it. -```json -{ - "pageHelp": { - "paragraphs": [ - { - "headline": "Introduction", - "values": [ - "Technology is moving fast and new technologies and innovations appear continuously.", - "It's essential for a development and technology company such as AOE to constantly improve and keep track with the latest useful innovations. It is important to openly look for innovations and new technologies and to question established technologies and methods every now and then.", - "But, it is also important to wisely choose which technologies to use in our daily work and in the different projects we are carrying out. As we all know: There is no silver bullet." - ] - }, - { - "headline": "What is the AOE Technology Radar", - "values": [ - "The Tech Radar is an overview of different technologies - from languages, frameworks, tools and patterns to platforms - that we consider \"new or mentionable\". The radar therefore doesn't provide an overview of all established technologies - but it focuses on items that have recently gained in importance or changed." - ] - } - ], - "quadrants": [ - { - "name": "Languages and Frameworks", - "description": "We've placed development languages (such as Scala or Golang) here, as well as more low-level development frameworks (such as Play or Symfony), which are useful for implementing custom software of all kinds." - }, - { - "name": "Tools", - "description": "Here we put different software tools - from small helpers to bigger software projects" - }, - { - "name": "Methods and Patterns", - "description": "Patterns are so important, and a lot of them are valid for a long time (compared to some tools or frameworks). So, this is the category where we put information on methods and patterns concerning development, continuous x, testing, organization, architecture, etc." - }, - { - "name": "Platforms and Operations", - "description": "(including AOE internal Services): Here we include infrastructure platforms and services. We also use this category to communicate news about AOE services that we want all AOE teams to be aware of." - } - ], - "rings": [ - { - "name": "Adopt", - "description": "We can clearly recommend this technology. We have used it for longer period of time in many teams and it has proven to be stable and useful." - }, - { - "name": "Trial", - "description": "We have used it with success and recommend to have a closer look at the technology in this ring. The goal of items here is to look at them more closely, with the goal to bring them to the adopt level." - }, - { - "name": "Assess", - "description": "We have tried it out and we find it promising. We recommend having a look at these items when you face a specific need for the technology in your project." - }, - { - "name": "Hold", - "description": "This category is a bit special. Unlike the others, we recommend to stop doing or using something. That does not mean that they are bad and it often might be ok to use them in existing projects. But we move things here if we think we shouldn't do them anymore - because we see better options or alternatives now." - } - ], - "sourcecodeLink": { - "href": "https://github.com/AOEpeople/aoe_technology_radar", - "name": "AOE Tech Radar on Github", - "description": "Contributions and source code of the AOE Tech Radar are on github:" - } - } -} -``` - -> The information in `description`s for `rings` and `quadrants` as well as the `values` for `paragraphs` may include HTML like `My Link` which will be sanitized. - -> For more information see the source code of the [Messages Context](./src/context/MessagesContext/index.tsx). - -## Development -Then simply start the dev server: -``` -npm run start -``` - -### Change scripts -If you change one of the scripts in the scripts' folder, you have to compile them to JavaScript. - -Therefore, run `npm run build:scripts` and commit the results in dist_scripts. - -To make it more robust the script will be executed on commit. +You can view a development version of the radar by running `npm run serve` and open the radar in +your +browser at `http://localhost:3000`. diff --git a/docs/assets/screenshot-techradar.png b/docs/assets/screenshot-techradar.png new file mode 100644 index 0000000..e562d8e Binary files /dev/null and b/docs/assets/screenshot-techradar.png differ diff --git a/package.json b/package.json index dbede26..4c2c3a5 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "aoe_technology_radar", - "version": "4.0.0-alpha.2", + "version": "4.0.0-alpha.3", "private": true, "bin": { "techradar": "./bin/techradar.sh"