/waka-readme

Wakatime Weekly Metrics on your Profile Readme.

Primary LanguagePythonMIT LicenseMIT

waka-readme

Dev Metrics in Readme Build Status

Project Preview

WakaTime Weekly Metrics on your Profile Readme:

Forum: GitHub Discussions

Prep Work

  1. You need to update a markdown file (.md) with 2 special comments. You can refer this to update it.
  2. You'll need a WakaTime API Key, which you can get from your WakaTime Account Settings. Click here, if you're new to WakaTime.
  3. Optionally you might need a GitHub API Token with repo scope, generated from here, if you're running this 'action' on any repo other than your profile repository. Then go to this example to work it out.
  4. You need to save the WakaTime API Key (and the GitHub API Token, if you need it) in the repository secrets. You can find that in your repository settings. Be sure to save those as the following.
    • WakaTime-api-key as WAKATIME_API_KEY = <your wakatime API Key> and
    • The GitHub Access Token as GH_TOKEN=<your github access token>
  5. You can follow either of the Two Examples according to your needs to get started with.

I strongly suggest you to run the 'Action' in your Profile Repo since you won't be needing a GitHub Access Token

This Action will run everyday at 00:00 UTC.

Update your Readme

Add comments to your README.md like this:

<!--START_SECTION:waka-->
<!--END_SECTION:waka-->

These lines will be the entry-points for dev metrics.

New to WakaTime?

WakaTime gives you an idea of the time you really spent on coding. This helps you boost your productivity and competitive edge.

Alternatively, you can also choose to fetch data from third-party WakaTime-compatible services like Wakapi or Hakatime instead. For details, see extras section below.

Profile Repository

If you're executing the workflow on your Profile Repository (<username>/<username>)

Please follow the steps below:

  1. Go to your <username>/<username>/actions, hit New workflow and set up a workflow yourself, then delete all the default content.

  2. Copy the following code and paste it to your new workflow file you just created and save/commit it as wakatime.yml.

    name: Waka Readme
    
    on:
      workflow_dispatch:
      schedule:
        # Runs at every 12AM UTC
        - cron: "0 0 * * *"
    
    jobs:
      update-readme:
        name: Update this repo's README
        runs-on: ubuntu-latest
        steps:
          - uses: athul/waka-readme@master
            with:
              WAKATIME_API_KEY: ${{ secrets.WAKATIME_API_KEY }}
  3. Go to your repo secrets by hitting Settings > Secrets. You can also enter the url https://github.com/USERNAME/USERNAME/settings/secrets/actions/new . Please replace the USERNAME with your own username.

  4. Create a new Secret. Name: WAKATIME_API_KEY and Value: Paste the Wakatime API key here.

    new-secrets-actions

    If you don't know what the key is, please go to Wakatime API to get your API Key (See New to WakaTime?).

    Add secret.

    5. Go to Action tab, click on Waka Readme, and Run workflow.

  5. Go to your profile page. you will be able to see it in 24 hrs.

Other Repository (not Profile)

If you're executing the workflow on another repo other than <username>/<username>

You'll need to get a GitHub Access Token with a repo scope and save it in the Repo Secrets GH_TOKEN = <Your GitHub Access Token>

Here is Sample Workflow File for running it:

name: Waka Readme

on:
  schedule:
    # Runs at 12am UTC
    - cron: "0 0 * * *"

jobs:
  update-readme:
    name: Update Readme with Metrics
    runs-on: ubuntu-latest
    steps:
      - uses: athul/waka-readme@master
        with:
          WAKATIME_API_KEY: ${{ secrets.WAKATIME_API_KEY }}
          GH_TOKEN: ${{ secrets.GH_TOKEN }}
          REPOSITORY: <username/username> # optional, By default, it will automatically use the repository which is executing the workflow.

Tests

Running Tests

To run tests simply execute the following in the directory containing main.py:

python -m unittest discover

Contributing Tests

These tests uses the python's unit testing framework.

Since this project is contained all within one file, main.py. You can simply add a function to the TestMain class in tests/test_main.py, similar to the test_graph function.

Extras

  1. You can specify the time range in the parameter (default last_7_days):

    - uses: athul/waka-readme@master
          with:
            WAKATIME_API_KEY: ${{ secrets.WAKATIME_API_KEY }}
            TIME_RANGE: last_30_days

    See Wakatime API docs for more possible values.

  2. If you want to add the week in the Header of your stats, you can add SHOW_TITLE: true (by default it will be false) in your workflow file like this

    - uses: athul/waka-readme@master
            with:
              WAKATIME_API_KEY: ${{ secrets.WAKATIME_API_KEY }}
              GH_TOKEN: ${{ secrets.GH_TOKEN }}
              SHOW_TITLE: true

    Here is an example output with SHOW_TITLE set to true.

    From: 12 February, 2022 - To: 19 February, 2022
    
    Python      8 hrs 52 mins       ███████████████████░░░░░░   75.87 %
    Go          1 hr 15 mins        ██░░░░░░░░░░░░░░░░░░░░░░░   10.79 %
    Markdown    52 mins             █░░░░░░░░░░░░░░░░░░░░░░░░   07.43 %
    Docker      16 mins             ░░░░░░░░░░░░░░░░░░░░░░░░░   02.32 %
    YAML        7 mins              ░░░░░░░░░░░░░░░░░░░░░░░░░   01.07 %
    
  3. You can specify a commit message to override the default "Updated the Graph with new Metrics". Here is how you do it

    - uses: athul/waka-readme@master
            with:
              WAKATIME_API_KEY: ${{ secrets.WAKATIME_API_KEY }}
              GH_TOKEN: ${{ secrets.GH_TOKEN }}
              COMMIT_MESSAGE: Updated the Readme

    If no commit message is specified in the yml file, it defaults to "Updated the Graph with new Metrics"

  4. You can change the block characters to match with the style of your readme. By default the one show in the graphs before is used. Here is how you do it

    - uses: athul/waka-readme@master
            with:
              WAKATIME_API_KEY: ${{ secrets.WAKATIME_API_KEY }}
              BLOCKS: ⣀⣄⣤⣦⣶⣷⣿

    It will change the graph to something like this:

    Python      8 hrs 52 mins       ⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣀⣀⣀⣀⣀⣀   75.87 %
    Go          1 hr 15 mins        ⣿⣿⣦⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀   10.79 %
    Markdown    52 mins             ⣿⣿⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀   07.43 %
    Docker      16 mins             ⣤⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀   02.32 %
    YAML        7 mins              ⣄⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀   01.07 %
    
  5. As an alternative to official WakaTime, waka-readme also integrates with WakaTime-compatible services like Wakapi and Hakatime. To use one of these, adapt the API URL accordingly and use the respective service's API key instead:

    - uses: athul/waka-readme@master
            with:
              WAKATIME_API_KEY: ${{ secrets.WAKATIME_API_KEY }}
              API_BASE_URL: https://wakapi.dev/api
  6. If you do not like to share how much time you spent on each language, you can add SHOW_TIME: false (by default it will be true) in your workflow file like so:

        - uses: athul/waka-readme@master
            with:
              WAKATIME_API_KEY: ${{ secrets.WAKATIME_API_KEY }}
              SHOW_TIME: false

    Here is an example output with SHOW_TIME set to false.

    From: 12 February, 2022 - To: 19 February, 2022
    
    PHP          ████████████████████▒░░░░░░░░░░░░░░░░░░░░   49.98 %
    Twig         ████▓░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░   11.07 %
    YAML         ████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░   09.77 %
    JavaScript   ██▓░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░   06.34 %
    Other        ██▒░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░   05.87 %
    

Why only the language stats and not other data from the API?

I am a fan of minimal designs and the profile readme is a great way to show off your skills and interests. The WakaTime API, gets us a lot of data about a person's coding activity including the editors and Operating Systems you used and the projects you worked on. Some of these projects maybe secretive and should not be shown out to the public. Using up more data via the Wakatime API will clutter the profile readme and hinder your chances on displaying what you provide value to the community like the pinned Repositories. I believe that Coding Stats is nerdiest of all since you can tell the community that you are exercising these languages or learning a new language, this will also show that you spend some amount of time to learn and exercise your development skills. That's what matters in the end ❤️