Version 2.10 (#30)
This commit is contained in:
Simon Lecoq
GitHub
111
CONTRIBUTING.md
111
CONTRIBUTING.md
@@ -6,69 +6,98 @@ 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
|
||||
#### Adding new metrics through GraphQL API, REST API or Third-Party service
|
||||
|
||||
When updating a single template, changes should be made through [GitHub GraphQL API](https://docs.github.com/en/graphql) 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 possible, try to use the [GitHub GraphQL API](https://docs.github.com/en/graphql) by editing queries in `source/queries` or the [GitHub Rest API](https://docs.github.com/en/rest). Use `puppeteer` in last resort.
|
||||
|
||||
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.
|
||||
Data computing and formatting should be made in `templates/*/template.mjs` if it's template specific, or in `templates/common.mjs` if it can be made available for all templates.
|
||||
|
||||
Raw queried data should be be exposed directly into `data.user`, whereas computed data should be stored in `data.computed`.
|
||||
|
||||
#### Updating SVG templates
|
||||
|
||||
The SVG templates are located in `templates/*/image.svg` and include CSS from `templates/*/style.css`.
|
||||
SVG templates are located in `templates/*/image.svg` and include CSS from `templates/*/style.css`.
|
||||
|
||||
It is rendered with [EJS](https://github.com/mde/ejs) so it is actually possible to include variables (e.g. `<%= user.name %>`) and execute simple code, like control statements.
|
||||
These are rendered through [EJS](https://github.com/mde/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.
|
||||
Exposed variables contains `user`, `computed` and `plugins` data, along with custom `style` and `fonts`.
|
||||
|
||||
#### Metrics server and GitHub action
|
||||
#### Creating a new plugin
|
||||
|
||||
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.
|
||||
Start by creating a new folder in `source/plugins`, along with its entry point `index.mjs`.
|
||||
|
||||
Metrics server code is located in `src/app.mjs` and instantiates an `express` server app, `octokit`s instances, middlewares (like rate-limiter) and routes.
|
||||
A plugin function has access to a lot of data, such as user's `login`, `rest` and `graphql` GitHub API handlers, `imports` of various utilitaries functions and modules, and various data. See others plugins for examples.
|
||||
|
||||
GitHub action code is located in `action/index.mjs` and instantiates `octokit`s instances and retrieves action parameters.
|
||||
It then use directly `src/metrics.mjs` to generate the SVG image and commit them to user's repository.
|
||||
Plugins should be self-sufficient and independant from others plugins.
|
||||
|
||||
Plugins errors should be handled gracefully by displaying an error message when it fails.
|
||||
|
||||
For user's convenience, a placeholder image can be generated to preview metrics without executing queries.
|
||||
This use a [Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) which "fills" with dummy data, though it has its limit (especially with iterable structures) so you may need to patch the placeholder function. It is located in `source/metrics.mjs`
|
||||
|
||||
When adding new options, be sure to patch both `action.yml` and `action/index.mjs` to support them.
|
||||
|
||||
#### Metrics web instance
|
||||
|
||||
Web instance code is located in `source/app.mjs` and instantiates an `express` server app.
|
||||
|
||||
#### GitHub action
|
||||
|
||||
GitHub action code is located in `action/index.mjs` and retrieves action parameters, which are converted into `q` parameters.
|
||||
Once SVG image is generated through `source/metrics.mjs`, it is committed 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.
|
||||
To test new features, setup a metrics web instance with a personal token and `debug` mode enabled.
|
||||
You can then test SVG renders in your browser and ensure that everything works as expected.
|
||||
|
||||
### 🗛 Fonts
|
||||
|
||||
Follow the following process to integrate custom fonts.
|
||||
It should be avoided when possible as it increases drastically the size of generated metrics.
|
||||
|
||||
1. Find a font on [fonts.google.com](https://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
|
||||
|
||||
### 🗂️ 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
|
||||
* `source/setup.mjs` contains configuration setup
|
||||
* `source/metrics.mjs` contains the metrics renderer
|
||||
* `source/templates/*` contains templates files
|
||||
* `source/templates/*/image.svg` contains the image template used to render metrics
|
||||
* `source/templates/*/style.css` contains the style used to render metrics
|
||||
* `source/templates/*/fonts.css` contains additional fonts used to render metrics
|
||||
* `source/templates/*/template.mjs` contains the code used to prepare metrics data before rendering
|
||||
* `source/plugins/*` contains source code of plugins
|
||||
* `source/queries/*` contains GraphQL queries
|
||||
|
||||
#### Metrics server instance
|
||||
#### Web 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
|
||||
* `index.mjs` contains metrics web instance entry point
|
||||
* `source/app.mjs` contains metrics web instance source code
|
||||
* `source/html/*` contains metrics web instance static files
|
||||
|
||||
#### GitHub action
|
||||
|
||||
* `action.yml` contains the GitHub action descriptor
|
||||
* `action/index.mjs` contains the GitHub action code
|
||||
* `action.yml` contains GitHub action descriptor
|
||||
* `action/index.mjs` contains GitHub action source 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
|
||||
|
||||
* `utils/build.mjs` contains a tool used to rebuild plugins and template indexes and GitHub action
|
||||
|
||||
### 📦 Used packages
|
||||
|
||||
@@ -100,17 +129,3 @@ It allows fast prototyping and to rapidly test SVG renders in a browser.
|
||||
* To print colors in console
|
||||
* [babel/minify](https://github.com/babel/minify)
|
||||
* To minify code
|
||||
|
||||
### 🗛 Fonts
|
||||
|
||||
1. Find a font on [fonts.google.com](https://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
|
||||
|
||||
Reference in New Issue
Block a user