4️⃣ Metrics v4 / Alpha preview

[lowlighter]

Note

While not available yet, metrics v4 is expected to be pre-released in the coming weeks.
You can track the progression in #1542, stay tuned 🚀 !

🧩 Plugins changes and new features

📰 Recent activity _activity

This plugin has been completly redesigned, to offer more data, code highlighting, and better event filtering.

📆 Commit calendar _calendar

Current isocalendar and calendar have been merged together to ensuring features consistency between both.

It means that you can now generate isometric calendars over multiples years, while the top-down calendar now have additional statistics along each year. You can also change colors more easily.

💻 Lines of code changed _lines

This plugin has been redesigned to offer more data granularity, where you'll be able to show diff per week and by contributor.
Additionally, the issue with the stats sometimes being empty have been fixed in this release!

🏛️ Legacy plugins _.legacy

It will take some time before all plugins and options are eventually migrated to v4.
Fortunately, the new .legacy plugin lets you call plugins directly from v3.x versions!

It will pull the corresponding docker image, pass your inputs, generate the render within v3 context and retrieve it inside the v4 engine.

If you switch from v3 to v4, the compatibility layer will automatically translates your current configuration with the new plugin syntax, and fallback on the .legacy plugin for the plugins that are not available yet.

plugins:
  - .legacy:
      version: v3.34
      inputs:
        plugin_isocalendar: yes
        plugin_isocalendar_duration: full-year

📦 Miscellaneous

All plugins are now entirely independant and can be used as standalones (they don't require base/core plugin execution anymore)

The following plugins have been migrated but don't really have any notable changes from a end-user point of view:

• 🎫 Gists
• 🙋 Introduction
• 🗼 Rss feed
• 📸 Webscraping

🪄 Processors and new features

The core plugin is being decommissioned entirely as it's being split into different "processors", which will offer more flexibility and power.

You can apply processors on a per-plugin basis, on even on a group basis using the .await plugin (which await for all previous plugins execution). Thanks to this you can now do neat tricks, such as using different templates per plugin, publishing your renders under different formats to various destinations, etc.

plugins:
  - introduction:
    template: terminal 
  - gists:
  - .await: 
    processors:
    - inject.style:
        style: .title { color: red; }
    - render:
        format: svg
    - optimize.css:
    - render.twemojis:
    - transform.base64:
    - publish.git:
        repository: my/repository-A
          commit:
            to: metrics-render-branch 
  - processors: # ".await" plugin is actually implicit :)
    - render:
        format: json
    - publish.gist:
        gist: ...

In the future, it is planned to offer more option to aggregate data together and also "rehydrate" data from cached data.

Below is a list of currently supported processors:

• 🧪 Assertions
• ⏰ Delay
• 🚩 Throw an error
• 🔩 Inject raw content
• 🔩 Inject JavaScript
• 🔩 Inject CSS
• 🧹 Optimize CSS
• 🧹 Optimize SVG
• 🧹 Optimize XML
• 📮 Publish to console
• 📮 Publish to local file
• 📮 Publish to GitHub Gist
• 📮 Publish to GitHub repository
• 🎨 Render image
• 🖋️ Render GitHub emojis
• 🖋️ Render GitHub octicons
• 🖋️ Render Twemojis
• 🏭 Transform images to base64 encoded images

🧼 Templates simplification

The classic template (the default one) is being reworked heavily.
The aim is to use simpler styling rules (without compromising design) to improve performances, but also to make it easily overridable by users through the new injection processors.

They're also designed to have better class conventions to make it easily manipulable with document.querySelector(). Additionnaly, styling related to single plugins are being moved out of the global stylesheet to avoid loading useless rules when a plugin is unused.

<section class="introduction">
  <div class="title">
    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16">...</svg>
    About ...
  </div>
  <div class="body">
    <!-- ... -->
  </div>
  <style>
    .introduction .text {
      white-space: normal;
      margin: 0 13px 2px;
    }
  </style>
</section>

🚂 An entirely rewritten engine focusing on...

🔐 Security

Metrics now support GitHub fine-grained tokens and deno permissions, which means you are guaranteed to have full control on which data this action has access to and what it can do with it.

Since specifying all permissions may be tedious, metrics is relying on deno_make and describe the "minimal permissions subset" in the deno.jsonc configuration file, but you are free to specify your own permissions !

🍱 Portability

Configuration syntax has been simplified and unified across the different modes of execution which are officially supported.
Same configuration file can now be reused across the different modes.

• Web server
• GitHub Action
• Docker image ^{🌟 Improved}
• Serverless ^{✨ New !}
• CLI / binary ^{✨ New !}

☁️ Deployability

Currently the web version is hosted on a server that I rent. Since it's managed by myself I sometimes forget to do it (who said "invalid ssl certificate" ?).

The plan with this new engine is to make it compatible with serverless services, such as deno deploy and vercel (with deno), and also to provide a docker image that is designed to be used outside of the metrics GitHub Action.

To achieve this, all features relying on prerequirements (browser, filesystem, etc.) are being abstracted so they can be replaced (for example the browser can use a remote service such as browserless.io or just being made optional). Feature parity may be impossible to achieve, but it should be close.

This change will also make contributions easier as we'll be able to test and preview new pull requests changes more easily.

🗿 Stability

Fully rewritten in TypeScript, configuration, inputs and outputs are now fully typed and strictly checked directly in the code with Zod, making it easier to work with Metrics.

/** Inputs */
readonly inputs = is.object({
  feed: is.string().url().default("https://news.ycombinator.com/rss").describe("RSS feed (e.g. `https://news.ycombinator.com/rss`)"),
  limit: is.number().int().min(1).nullable().default(4).describe("Display limit. Set to `null` to disable"),
})

/** Outputs */
readonly outputs = is.object({
  name: is.string().describe("Feed name"),
  description: is.string().describe("Feed description"),
  entries: is.array(is.object({
    title: is.string().describe("Entry title"),
    link: is.string().url().describe("Entry link"),
    date: is.date().nullable().describe("Entry date"),
  })).describe("Feed entries"),
})

🔄 Versatility

While it is not entirely ready yet, in the future you will be able to import metrics plugin and processors directly in external programs. The new inputs/outputs validations schemas ensure a stable API with consistant results.

So you can built new apps upon metrics:

import { Plugin } from "https://deno.land/x/metrics/plugins/mod.ts";
const { result } = await Plugin.run({
  context: {
    id: "introduction",
    entity: "user",
    handle: "octocat",
    retries: {},
    mock: true
  }
})

🧪 Reliability

The code is now tested more thoroughly with better tests and less hacky workarounds. It also now features code coverage.
The aim is to provide a fully tested codebase with a coverage close to 100%.

⚡ Rapidity

The boot-time is now significantly lower as code has been refactored and optimized to decrease bottlenecks (no more dependencies on base and core plugins, and no need to load up all plugins at startup).

Most of queries have been optimized to consume less requests, and templates have been refactored to reduce the number of nodes created to make simpler outputs.

Unlike node_modules, ESM modules offers easier tree-shaking which also means that running a non-cached version of the code will be faster as only the used code will be fetched to run it

♻️ Reusability

As mentionned previously, same plugin can now be called multiple times using differents scopes and contexts (e.g. different users, tokens, timezones, api endpoints, templates, etc.).

The end goal is to offer an easier version of the existing presets system by integrating it directly in the configuration file.
It means that you will be able to reuse a configuration from another user just by overriding the variables you want to.

plugins:
  - calendar:
      handle: octocat
      token: ${{ secrets.TOKEN_OCTOCAT }}
      timezone: Europe/Paris
  - calendar:
      handle: octodog
      token: ${{ secrets.TOKEN_OCTODOG }}
      timezone: America/Montreal

🎴 Extensibility

Using the power of ESM modules, you can easily include remote versions of plugins and templates (perfect to rollback a given plugin on a specific version or to use a custom version of it). Less patches to apply and more flexibility!

plugins:
  - https://raw.githubusercontent.com/lowlighter/metrics/v4/source/plugins/calendar/mod.ts:
      handle: octocat
    template: https://raw.githubusercontent.com/lowlighter/metrics/v4/source/plugins/calendar/templates/classic.ejs

🏛️ Compatibility

Configurations from v3 and earlier versions will still work thanks to the compatibility layer which will automatically convert old inputs into the new v4 format, and offering suggestions and tips for migration. Apart from really niche options and design changes, migrating will be almost transparent.

🧰 Ergonomy

The web UI has been entierly redesigned with Alpine.js and Tailwind CSS to make it simpler and friendlier. The inputs are now auto-generated through the inputs JSON schemas. Thanks to the improved test data, mocked previews are now more close to what will eventually be generated

🤝 Community

While the old codebase survived more than 50 versions, it wasn't really friendly for new contributions.
This rewrite hopes to make it easier to contribute by:

• Providing a clean codebase which is fully typed, commented, tested and covered
• Making it easier to setup and deploy by only requiring deno to be installed, and officially supporting serverless services
• Simplifying how to add plugins by making them self-contained (code, tests, templates and docs), and make it easier to use custom plugins and templates not from the official codebase

💪 Interested in contributing ?
Check out issues with the 🆕 v4 label
Contributions for v4 will be accepted once #1542 is landed
Whether it's to migrate old plugins from v3 to v4, or create new plugins or options, all contributions are welcomed !

💕 Liking (the future of) metrics ?
You can sponsor me to support development !
Even one-time contributions are welcomed 🥰

Tip

📮 Constructive feedback (whether positive or negative) is welcomed !
If something isn't clear, about the new engine, the migration or anything, don't hesitate to ask !

[Andre601]

Can we already use the v4 branch to start working on plugin updates?
Or would it be better to wait for its initial release?

[lowlighter]

I think it's better to wait until #1542 lands

I'm still moving stuff around, and the end-user interface is not finalized yet which would make developing/testing a bit tedious. The lack of documentation won't help too, as these are still being written

But yeah theoretically it's possible to already use the v4-dev to test it, but give it one or two weeks more and it should be stable enough to start working on it 😄

[Andre601]

How is the current state of v4 so far? I haven't seen any notable updates to the PR #1542, so I'm wondering if it is currently on standby for whatever reason there may be...