diff --git a/README.md b/README.md index 7849d5b..872031d 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,143 @@ # Data and Analytics Engineering Tech Radar -In the MoJ [Data and Analytics Engineering community](https://ministryofjustice.github.io/data-and-analytics-engineering/), -we maintain a [public Tech Radar](http://zalando.github.io/tech-radar/) to help our teams -align on technology choices. It is based on the [pioneering work +The MoJ [Data and Analytics Engineering community](https://ministryofjustice.github.io/data-and-analytics-engineering/), +maintains a [public Tech Radar](http://zalando.github.io/tech-radar/) to help +align technology choices within our teams. This Tech Radar is based on [pioneering work by ThoughtWorks](https://www.thoughtworks.com/radar) and uses a modified version of Zalando's -[`radar.js`](https://github.com/zalando/tech-radar/blob/master/docs/radar.js) [d3.js v4](https://d3js.org) tech radar visualisation. +[`radar.js`](https://github.com/zalando/tech-radar/blob/master/docs/radar.js) with [d3.js v4](https://d3js.org) for visualisation. -Tech radar blips are configured in `blips.json` against tech radar rings -and quadrants configured in `radar_config.json`. +Tech radar blips are configured in `blips.json`, while tech radar rings and quadrants are set up in `radar_config.json`. Additional context for the blips is provided by GitHub discussions, which are queried using the GitHub GraphQL API to populate `blips.json` -GitHub discussions provide additional context to the blips, -which are queried using the GitHub graphql API to populate `blips.json`. \ No newline at end of file + +# Tech Radar Discussion Management + +This script extracts technology radar entries from [the tech radar GitHub Discussions](https://github.com/moj-analytical-services/data-and-analytics-engineering-tech-radar/discussions) and outputs them in a structured `JSON` format used by the visualization framework. It can also compare the extracted data with a previous snapshot to identify changes. + + + +## Setup + +### Clone the Repository: + +```bash +git clone git@github.com:moj-analytical-services/data-and-analytics-engineering-tech-radar.git +``` +```bash +cd data-and-analytics-engineering-tech-radar +``` +### Create `.env` File: + +Create a file named `.env` in the script's directory and add your GitHub personal access token in the following format: +```bash +GH_TOKEN= +``` +Replace `` with your actual GitHub personal access token (PAT) that has the necessary permissions for GraphQL API access. + +**For GitHub Personal Access Token:** +
    +
  1. Go to your [GitHub account settings](https://github.com/settings/profile).
    2. +
  2. Navigate to Developer settings -> Personal access tokens.
    3. +
  3. Click Generate new token and select the repo scope.
    4. +
  4. Copy the generated token into the .env file.
    5. + +
+ +### Create and activate a virtual environment: + +``` +python -m venv venv +source venv/bin/activate +``` +### Install the python packages required + + +```pythpn +pip install -r requirements.txt +``` + +## Configure `radar_config.json`: +Create a file named `radar_config.json` to define your radar's structure: + +```json +{ + "quadrants": [ + {"name": "Quadrant 1 Name", + "_location": "Top"}, + {"name": "Quadrant 2 Name", + "_location": "Bottom"}, + ... + ], + "rings": [ + {"name": "Ring 1 Name", "emoji": "โœ…"}, + {"name": "Ring 2 Name", "emoji": "๐Ÿงช"}, + ... + ] +} +``` + +**Example:** +```json +{ + "quadrants": [ + {"name": "Techniques"}, + {"name": "Platforms"}, + {"name": "Languages & Frameworks"}, + {"name": "Data Tools"} + ], + "rings": [ + {"name": "Adopt", "emoji": "โœ…"}, + {"name": "Trial", "emoji": "๐Ÿงช"}, + {"name": "Assess", "emoji": "๐Ÿ”Ž"}, + {"name": "Hold", "emoji": "๐Ÿ›‘"} + ] +} +``` + +#### (Optional) Prepare `blips.json` for Comparison: + + If you want to compare with previous data, create a `blips.json` file with the following structure: + +```json +{ + "date": "YYYY-MM-DD", + "entries": [ + { + "label": "Entry 1 Label", + "quadrant": 0, + "ring": 2 + }, + ... + ] +} +``` + +### Usage + +#### Run the Script +```bash +python manage_discussions/get_discussions.py +``` +### Output + +The script will generate two JSON files: + +- `blips.json`: Contains the extracted radar entries with the current date, which also updates the visualization. + +- `entries_skipped.json`: (If any) Lists discussions that didn't match the criteria for radar entries. + + +### Viewing the Output Locally in VS Code +#### Install Live Server Extension +
    +
  1. Open Visual Studio Code: Launch VS Code on your computer.
    2. +
  2. Access Extensions: Click on the Extensions icon in the Activity Bar on the side of the window.
    3. +
  3. Search for Live Server: In the Extensions view, type "Live Server" in the search bar.
    4. +
  4. Install Live Server: Click on the Install button for the Live Server extension.
    5. +
+ +#### Start Live Server + +
    +
  1. Open Your Project: Open the folder containing your project files, including index.html
    2. +
  2. Start Live Server: Right-click on your index.html file and select "Open with Live Server" from the context menu.
    3. +
diff --git a/entries_skipped.json b/entries_skipped.json new file mode 100644 index 0000000..e69de29 diff --git a/index.html b/index.html index 9a5a296..f00e342 100644 --- a/index.html +++ b/index.html @@ -9,8 +9,8 @@ - - + + diff --git a/manage_discussions/get_discussions.py b/manage_discussions/get_discussions.py index 50ef14f..b5733d3 100644 --- a/manage_discussions/get_discussions.py +++ b/manage_discussions/get_discussions.py @@ -88,6 +88,9 @@ ring_old = blips_old.get(details['title']) if ring_old is not None: ring_change = ring_old - ring + else: + # Set ring_change to 2 if it's a new entry + ring_change = 2 entries_new.append({"label":details['title'], "quadrant":quadrant, "ring":ring,