metrics/CONTRIBUTING.md

📊 GitHub metrics

💪 Interested in contributing ?

Nice ! Read the few sections below to understand how this project is structured.

👨‍💻 General informations

Adding new metrics and plugins through GraphQL API, REST API or Third-Party service

When updating a single template, changes should be made through GitHub GraphQL API by editing the GraphQL query from templates/*/query.graphql. Computed or formatting can be made in templates/*/template.mjs. Raw queried data should be exposed directly into data.user, whereas computed data should be stored in data.computed.

When making a new plugin, a new folder with its name must be created in src/plugins. Plugins entry point src/plugins/*/index.mjs will have access to {login, q, imports, data, computed, rest, graphql}. It should be self-sufficient and independant from others plugins and used template. Data generated should be exposed in data.computed.plugins[plugin] where plugin is the plugin's name.

Updating SVG templates

The SVG templates are located in templates/*/image.svg and include CSS from templates/*/style.css.

It is rendered with EJS so it is actually possible to include variables (e.g. <%= user.name %>) and execute simple code, like control statements.

Plugins errors should be handled gracefully by displaying the error message.

Metrics server and GitHub action

Unless when integrating new features directly tied to these, it is not needed to edit them when creating a new template or plugin. Keep in mind that SVG image is actually generated from src/metrics.mjs, independently from the metrics server and GitHub action.

Metrics server code is located in src/app.mjs and instantiates an express server app, octokits instances, middlewares (like rate-limiter) and routes.

GitHub action code is located in action/index.mjs and instantiates octokits instances and retrieves action parameters. It then use directly src/metrics.mjs to generate the SVG image and commit them to user's repository.

Testing new features

To test new features, setup a metrics server with a test token and debug mode enabled. It allows fast prototyping and to rapidly test SVG renders in a browser.

🗂️ Project structure

Metrics generator

• src/setup.mjs contains the configuration setup
• src/metrics.mjs contains the metrics renderer
• src/templates/* contains templates files
• src/templates/*/image.svg contains the template used by the generated SVG image
• src/templates/*/query.graphql is the GraphQL query sent to GitHub GraphQL API
• src/templates/*/style.css contains the style used by the generated SVG image
• src/templates/*/template.mjs contains the code which prepares data for rendering
• src/plugins/* contains the source code of metrics plugins

Metrics server instance

• index.mjs contains the metrics server entry point
• src/app.mjs contains the metrics server code which serves, renders, restricts/rate limit, etc.
• src/html/* contains the metrics server static files

GitHub action

• action.yml contains the GitHub action descriptor
• action/index.mjs contains the GitHub action code
• action/dist/index.js contains compiled the GitHub action code (auto-generated)

Others

• tests/metrics.mjs contains tests
• utils/build.mjs allows to rebuild plugins and template indexes and GitHub action

📦 Used packages

• express/express.js and expressjs/compression
  • To serve, compute and render a GitHub user's metrics
• nfriedly/express-rate-limit
  • To apply rate limiting on server and avoid spams and hitting GitHub API's own rate limit
• octokit/graphql.js and octokit/rest.js
  • To perform request to GitHub GraphQL API and GitHub REST API
• mde/ejs
  • To render SVG images
• ptarjan/node-cache
  • To cache generated content
• renanbastos93/image-to-base64
  • To generate base64 representation of users' avatars
• svg/svgo
  • To optimize generated SVG
• axios/axios
  • To make HTTP/S requests
• actions/toolkit and vercel/ncc
  • To build the GitHub Action
• vuejs/vue and egoist/vue-prism-component + PrismJS/prism
  • To display server application
• puppeteer/puppeteer
  • To scrap the web
• libxmljs/libxmljs
  • To test and verify SVG validity
• Marak/colors.js
  • To print colors in console
• babel/minify
  • To minify code

🗛 Fonts

1. Find a font on fonts.google.com

• Select regular, bold, italic and bold+italic fonts
• Open embed tab and extract the href

2. Open extracted href and append &text= params with used characters from SVG

• e.g. &text=%26%27"%7C%60%5E%40°%3F!%23%24%25()*%2B%2C-.%2F0123456789%3A%3B<%3D>ABCDEFGHIJKLMNOPQRSTUVWXYZ%5B%5D_abcdefghijklmnopqrstuvwxyz%7B%7D~─└├▇□✕

3. Download each font file from url links from the generated stylesheet
4. Convert them into base64 with woff extension on [transfonter.org]https://transfonter.org/) and download archive
5. Extract archive and copy the content of the generated stylesheet to templates/*/fonts.css
6. Update your template

• Include <defs><style><%= fonts %></style></defs> to your templates/*/image.svg
• Edit your templates/*/style.css to use yout new font