From 46059eb3c1699589826b0cfb288d08331dcdaf43 Mon Sep 17 00:00:00 2001 From: Simon Schneegans Date: Sat, 15 Aug 2020 22:00:28 +0200 Subject: [PATCH] :memo: Write some documentation --- README.md | 128 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 116 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 3b017c5..c8ae780 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,125 @@ -# Hello world javascript action +# Dynamic Badges Action -This action prints "Hello World" or "Hello" + the name of a person to greet to the log. +[![license](https://img.shields.io/badge/License-MIT-purple.svg)](LICENSE) -## Inputs +This action allows you to create badges with shields.io which may change with every commit which can be embedded in your README.md. To do this, this action does not need to push anything to your repository! -### `who-to-greet` +This action supports all [configuration options of shields.io/endpoint](https://shields.io/endpoint) and can be used in various ways: +* Show custom CI statistics from GitHub actions, such as code coverage or detailed test results. +* Show metadata of your repository such as lines of code, comment line percentage, ... +* Basically anything which may change from commit to commit! -**Required** The name of the person to greet. Default `"World"`. +## How Does It Work? -## Outputs +Whenever this action is executed, it creates a JSON object based on the input parameters. +This JSON object may look like this: -### `time` +```json +{ + "schemaVersion": 1, + "label": "Hello", + "message": "World", + "color": "orange" +} +``` -The time we greeted you. +This JSON object is then uploaded as a file to a [*gist*](https://gist.github.com/) and can be transformed to a badge like ![license](https://img.shields.io/badge/Hello-World-orange.svg) with shields.io/endpoint: -## Example usage +``` +https://img.shields.io/endpoint?url=https://gist.githubusercontent.com///raw/ +``` -uses: actions/hello-world-javascript-action@v1 -with: - who-to-greet: 'Mona the Octocat' \ No newline at end of file +## Configuration + +1. Head over to gist.github.com and create a new gist. You will need the ID of the gist (this is the long alphanumerical part of its URL) later. +2. Navigate to github.com/settings/tokens and create a new token with the *gist* scope. +3. Go to the *Secrets* page of the settings of your repository and add this token as a new secret. You can give it any name, for example `GIST_SECRET`. +4. Add something like the following to your workflow: +```yml +- name: Create Awesome Badge + uses: schneegans/dynamic-badges-action@v1 + with: + auth: ${{ secrets.GIST_SECRET }} + gistID: + filename: test.json + label: Hello + message: World + color: orange +``` + +Once the action is executed, got to your gist. +There should be a new file called `test.json`. +You can view the raw content of this file at `https://gist.githubusercontent.com///raw/test.json`. +Embed the badge with: + +```markdown +![badge](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com///raw/test.json) +``` + +### Input Parameters + +The **Badge Parameters** are directly passed to shields.io. See the [official documentation](https://shields.io/endpoint) for more detailed explanations. + +Gist Parameter | Description +----------|------------ +`auth` | Required. A secret token with the *gist* scope. +`gistID` | Required. The ID of the target gist. Something like `8f6459c2417de7534f64d98360dde866`. +`filename` | Required. The target filename - each gist may contain several files. This should have the `.json` extension. +**Badge Parameter** | **Description** +`label` | Required. The left text of the badge. +`message` | Required. The right text of the badge. +`labelColor` | The left color of the badge. +`color` | The right color of the badge. +`isError` | The color will be red and cannot be overridde.n +`namedLogo` | A logo name from simpleicons.org. +`logoSvg` | An svg-string to be used as logo. +`logoColor` | The color for the logo. +`logoWidth` | The space allocated for the logo. +`logoPosition` | The position of the logo. +`style` | The style like "flat" or "social". +`cacheSeconds` | The cache lifetime in seconds (must be greater than 300). + +### Using Environment Variables as Parameters + +A common usage pattern of this action is to create environment variables in previous steps of a job and later use them as message in your badge. This can be achieved like this: + +```yml +- name: Calculate the Number + run: echo "::set-env name=ANSWER::42" +- name: Create the Badge + uses: schneegans/dynamic-badges-action@v1 + with: + auth: ${{ secrets.GIST_SECRET }} + gistID: + filename: answer.json + label: The Answer is + message: ${{ env.ANSWER }} + color: purple +``` + +# Contributing to Dynamic Badges Action + +Whenever you encounter a :beetle: **bug** or have :tada: **feature request**, +report this via [Github issues](https://github.com/schneegans/dynamic-badges-action/issues). + +We are happy to receive contributions in the form of **pull requests** via Github. +Feel free to fork the repository, implement your changes and create a merge request to the `master` branch. + +## Git Commit Messages + +Commits should start with a Capital letter and should be written in present tense (e.g. __:tada: Add cool new feature__ instead of __:tada: Added cool new feature__). +You should also start your commit message with **one** applicable emoji. This does not only look great but also makes you rethink what to add to a commit. Make many but small commits! + +Emoji | Description +------|------------ +:tada: `:tada:` | When you added a cool new feature. +:wrench: `:wrench:` | When you refactored / improved a small piece of code. +:hammer: `:hammer:` | When you refactored / improved large parts of the code. +:sparkles: `:sparkles:` | When you applied clang-format. +:art: `:art:` | When you improved / added assets like themes. +:rocket: `:rocket:` | When you improved performance. +:memo: `:memo:` | When you wrote documentation. +:beetle: `:beetle:` | When you fixed a bug. +:twisted_rightwards_arrows: `:twisted_rightwards_arrows:` | When you merged a branch. +:fire: `:fire:` | When you removed something. +:truck: `:truck:` | When you moved / renamed something. \ No newline at end of file