From d97f76b4088fe3903dd0dc96256400988389321a Mon Sep 17 00:00:00 2001 From: Kitty Chiu <42864823+KittyChiu@users.noreply.github.com> Date: Thu, 17 Aug 2023 09:54:45 +1000 Subject: [PATCH] doc: updated documentation (#14) * doc: updated CONTRIBUTING * doc: fixed typo * update --- .github/workflows/docker-image.yml | 2 -- CONTRIBUTING.md | 50 ++++++++++++++++++++++++++++-- README.md | 20 +++++++----- action.yml | 3 ++ 4 files changed, 63 insertions(+), 12 deletions(-) diff --git a/.github/workflows/docker-image.yml b/.github/workflows/docker-image.yml index 96bac81..f0f7c2d 100644 --- a/.github/workflows/docker-image.yml +++ b/.github/workflows/docker-image.yml @@ -4,8 +4,6 @@ name: Docker Image CI on: push: branches: [ main ] - pull_request: - branches: [ main ] jobs: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c402042..a0e9416 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,49 @@ -# Contributing to workflow-metrics +# Contributing to `workflow-metrics` -TBA +Thank you for your interest in contributing to `workflow-metrics`! We welcome contributions from everyone, and we appreciate your help in making this action better. + +## Getting Started + +Before you start contributing, please make sure that you have read the [README.md](./README.md) file and have a basic understanding of the action. + +## How to Contribute + +There are many ways to contribute to `workflow-metrics`, from writing code to submitting bug reports. Here are some ways that you can contribute: + +### Submitting Issues + +If you find a bug or have a feature request, please submit an issue on the [GitHub issue tracker](https://github.com/kittychiu/workflow-metrics/issues). Please include as much detail as possible, including steps to reproduce the issue and any relevant error messages. + +### Contributing Code + +If you would like to contribute code to `workflow-metrics`, please follow these steps: + +1. Fork the repository on GitHub. +2. Clone your forked repository to your local machine. +3. Create a new branch for your changes. +4. Make your changes and commit them to your branch. +5. Push your changes to your forked repository on GitHub. +6. Submit a pull request to the main repository. + +Please make sure that your code follows the [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guide and includes tests for any new functionality. + +### Contributing Documentation + +If you would like to contribute documentation to `workflow-metrics`, please follow these steps: + +1. Fork the repository on GitHub. +2. Clone your forked repository to your local machine. +3. Create a new branch for your changes. +4. Make your changes and commit them to your branch. +5. Push your changes to your forked repository on GitHub. +6. Submit a pull request to the main repository. + +Please make sure that your documentation follows the [Markdown syntax](https://www.markdownguide.org/basic-syntax/) and is clear and concise. + +## Code of Conduct + +Please note that this project is released with a [Contributor Code of Conduct](./CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms. + +## License + +`workflow-metrics` is released under the [MIT License](./LICENSE). diff --git a/README.md b/README.md index 3011239..9758a33 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # Workflow Metrics Action +[![CodeQL](https://github.com/KittyChiu/workflow-metrics/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/KittyChiu/workflow-metrics/actions/workflows/github-code-scanning/codeql) [![Docker Image CI](https://github.com/KittyChiu/workflow-metrics/actions/workflows/docker-image.yml/badge.svg)](https://github.com/KittyChiu/workflow-metrics/actions/workflows/docker-image.yml) + This GitHub Action provides a way to evaluate statistics for your GitHub Actions workflows. With this action, you can easily monitor the performance of your workflows and identify areas for improvement. Metrics that are evaluated are: @@ -25,7 +27,7 @@ The following options are available for configuring the action: | --- | --- | --- | --- | | `GH_TOKEN` | Yes | N/A | A GitHub token with access to the repository. Minimal scope is `repo` | | `OWNER_NAME` | Yes | N/A | Name of the repository owner. | -| `REPO_NAME` | No | N/A | Name of the repository. If `REPO_NAME` is not provide, the action will analyse all the workflow runs in the organisation. | +| `REPO_NAME` | No | N/A | Name of the repository. If `REPO_NAME` is not provided, the action will analyse all the workflow runs in the organisation. | | `START_DATE` | Yes | N/A | Start date for the workflow runs data set. This should be in the format `YYYY-MM-DD`. | | `END_DATE` | Yes | N/A | End date for the workflow runs data set. This should be in the format `YYYY-MM-DD`. | | `DELAY_BETWEEN_QUERY` | No | N/A | No. of seconds to wait between queries to the GitHub API. This is to prevent errors from rate limiting when analysing the whole org. | @@ -37,6 +39,7 @@ After the action has completed, two files will be created in the root of the run - `runs.json` or `org-runs.json` - a JSON array of all workflow runs in the specified time range for the specified repository or organization. - `workflow-stats.csv` or `org-workflow-stats.csv` - a CSV file with workflow run statistics for the specified repository or organization. +These are data files that then can be used for further analysis or reporting in visualizer of your choice. For example, you can ingest into datastore and visualize with PowerBI. Below are some examples on generating markdown table and mermaid diagram with the data files ## Example usages @@ -57,7 +60,7 @@ jobs: uses: actions/checkout@v3 - name: Call workflow-runs action - uses: KittyChiu/workflow-metrics@v0.4.5 + uses: kittychiu/workflow-metrics@v0.4.7 env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} OWNER_NAME: "myOrg" @@ -118,7 +121,7 @@ jobs: echo "REPO_NAME=${repo}" >> $GITHUB_ENV - name: Call workflow-runs action - uses: KittyChiu/workflow-metrics@v0.4.5 + uses: kittychiu/workflow-metrics@v0.4.7 env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} REPO_NAME: ${{ env.REPO_NAME }} @@ -195,7 +198,6 @@ jobs: runs-on: ubuntu-latest env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - OWNER_NAME: ${{ github.repository_owner }} steps: - name: Checkout code @@ -207,12 +209,14 @@ jobs: echo "END_DATE=$(date +%Y-%m-%d)" >> "$GITHUB_ENV" - name: Test docker action - uses: KittyChiu/workflow-metrics@v0.4.5 + uses: kittychiu/workflow-metrics@v0.4.7 env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GH_TOKEN: ${{ env.GH_TOKEN }} + OWNER_NAME: ${{ github.repository_owner }} START_DATE: ${{ env.START_DATE }} END_DATE: ${{ env.END_DATE }} - + DELAY_BETWEEN_QUERY: 5 + - name: Convert org-workflow-stats.csv to stats-table.md markdown table run: | echo -e "## Table View\n" > stats-table.md @@ -246,7 +250,7 @@ Below is an example of the `stats-table.md` file: |repo_1|Test|3.00|3.00|100.00|1| |repo_1|Build|20.20|17.00|80.00|5| |repo_1|Deploy|17.00|17.00|100.00|1| -|repo_2|Governance Validation|2.00|2.00|100.00|1| +|repo_2|Custom Validation|2.00|2.00|100.00|1| |repo_2|Linter|2.00|2.00|100.00|1| |repo_3|Superlinter|25.38|23.00|30.00|50| |repo_3|Long Build|36.17|36.50|53.70|54| diff --git a/action.yml b/action.yml index 6f09532..5ff0a91 100644 --- a/action.yml +++ b/action.yml @@ -4,3 +4,6 @@ description: Generate metrics for historical workflow runs runs: using: 'docker' image: 'docker://ghcr.io/kittychiu/workflow-metrics:v1' +branding: + icon: 'rss' + color: 'orange' \ No newline at end of file