docs: update README (take over #131)

.gitignore

@@ -143,3 +143,7 @@ cython_debug/
 
 # Mac
 .DS_Store
+**/.DS_Store
+
+# PyCharm
+.idea/

docs/assign-team-instead-of-individual.md

@@ -0,0 +1,60 @@
+## Assigning teams instead of individuals
+
+The assignee part of this workflow action comes from [a different GitHub action](https://github.com/peter-evans/create-issue-from-file) and currently GitHub issues don't support assigning groups.
+
+By way of work around, you could use the [GitHub API to retrieve the members of the team](https://docs.github.com/en/rest/teams/members?apiVersion=2022-11-28#list-team-members) and then put them in a comma separated string that you provide as the assignee. This requires setting up a new GitHub API token (referred to below as `CUSTOM_TOKEN`) which has `read:org` permissions assigned and single sign on authorization as needed. To do this, create a [GitHub API token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) with permissions to read the org (`read:org`). Then take the value of the API token you just created, and [create a repository secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets) where the name of the secret is `CUSTOM_TOKEN` and the value of the secret the API token.
+
+That might look something like the workflow below where `ORG` is your organization name and `TEAM_SLUG` is the name of the team:
+
+```yaml
+name: Monthly issue metrics
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '3 2 1 * *'
+
+permissions:
+  issues: write
+  pull-requests: read
+
+jobs:
+  build:
+    name: issue metrics
+    runs-on: ubuntu-latest
+
+    steps:
+
+    - name: Get dates for last month
+      shell: bash
+      run: |
+        # Calculate the first day of the previous month
+        first_day=$(date -d "last month" +%Y-%m-01)
+
+        # Calculate the last day of the previous month
+        last_day=$(date -d "$first_day +1 month -1 day" +%Y-%m-%d)
+
+        #Set an environment variable with the date range
+        echo "$first_day..$last_day"
+        echo "last_month=$first_day..$last_day" >> "$GITHUB_ENV"
+
+    - name: Run issue-metrics tool
+      uses: github/issue-metrics@v2
+      env:
+        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        SEARCH_QUERY: 'repo:owner/repo is:issue created:${{ env.last_month }} -reason:"not planned"'
+
+    - name: Get user names from team
+      run: |
+          teamMembers="$(gh api /orgs/ORG/teams/TEAM_SLUG/members | jq -r '.[].login' | paste -sd, -)"
+          echo 'TEAM_MEMBERS='$teamMembers >> $GITHUB_ENV
+        env:
+          GITHUB_TOKEN: ${{ secrets.CUSTOM_TOKEN }}
+
+    - name: Create issue
+      uses: peter-evans/create-issue-from-file@v4
+      with:
+        title: Monthly issue metrics report
+        token: ${{ secrets.GITHUB_TOKEN }}
+        content-filepath: ./issue_metrics.md
+        assignees: ${{ env.TEAM_MEMBERS }}
+```

docs/example-using-json-instead-markdown-output.md

@@ -0,0 +1,33 @@
+
+## Example using the JSON output instead of the markdown output
+
+There is JSON output available as well. You could use it for any number of possibilities, but here is one example that demonstrates retreiving the JSON output and then printing it out.
+
+```yaml
+name: Monthly issue metrics
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '3 2 1 * *'
+
+permissions:
+  issues: write
+  pull-requests: read
+
+jobs:
+  build:
+    name: issue metrics
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Run issue-metrics tool
+      id: issue-metrics
+      uses: github/issue-metrics@v2
+      env:
+        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        SEARCH_QUERY: 'repo:owner/repo is:issue created:2023-05-01..2023-05-31 -reason:"not planned"'
+
+    - name: Print output of issue metrics tool
+      run: echo "${{ steps.issue-metrics.outputs.metrics }}"
+
+```

docs/example-workflows.md

@@ -0,0 +1,136 @@
+
+### Example workflows
+
+#### Calculated Time Example
+This workflow searches for the issues created last month, and generates an issue with metrics.
+
+```yaml
+name: Monthly issue metrics
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '3 2 1 * *'
+
+permissions:
+  issues: write
+  pull-requests: read
+
+jobs:
+  build:
+    name: issue metrics
+    runs-on: ubuntu-latest
+
+    steps:
+
+    - name: Get dates for last month
+      shell: bash
+      run: |
+        # Calculate the first day of the previous month
+        first_day=$(date -d "last month" +%Y-%m-01)
+
+        # Calculate the last day of the previous month
+        last_day=$(date -d "$first_day +1 month -1 day" +%Y-%m-%d)
+
+        #Set an environment variable with the date range
+        echo "$first_day..$last_day"
+        echo "last_month=$first_day..$last_day" >> "$GITHUB_ENV"
+
+    - name: Run issue-metrics tool
+      uses: github/issue-metrics@v2
+      env:
+        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        SEARCH_QUERY: 'repo:owner/repo is:issue created:${{ env.last_month }} -reason:"not planned"'
+
+    - name: Create issue
+      uses: peter-evans/create-issue-from-file@v4
+      with:
+        title: Monthly issue metrics report
+        token: ${{ secrets.GITHUB_TOKEN }}
+        content-filepath: ./issue_metrics.md
+        assignees: <YOUR_GITHUB_HANDLE_HERE>
+
+```
+
+#### Fixed Time Example
+This workflow searches for the issues created between 2023-05-01..2023-05-31, and generates an issue with metrics.
+
+```yaml
+name: Monthly issue metrics
+on:
+  workflow_dispatch:
+
+permissions:
+  issues: write
+  pull-requests: read
+
+jobs:
+  build:
+    name: issue metrics
+    runs-on: ubuntu-latest
+
+    steps:
+
+    - name: Run issue-metrics tool
+      uses: github/issue-metrics@v2
+      env:
+        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        SEARCH_QUERY: 'repo:owner/repo is:issue created:2023-05-01..2023-05-31 -reason:"not planned"'
+
+    - name: Create issue
+      uses: peter-evans/create-issue-from-file@v4
+      with:
+        title: Monthly issue metrics report
+        token: ${{ secrets.GITHUB_TOKEN }}
+        content-filepath: ./issue_metrics.md
+        assignees: <YOUR_GITHUB_HANDLE_HERE>
+
+```
+
+
+#### Multiple Repositories Example
+
+This workflow searches for the issues created last month, and generates an issue with metrics. It also searches for issues in a second repository and includes those metrics in the same issue.
+
+```yaml
+name: Monthly issue metrics (Multi Repo)
+on:
+  workflow_dispatch:
+
+permissions:
+  issues: write
+  pull-requests: read
+
+jobs:
+  build:
+    name: issue metrics
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Get dates for last month
+        shell: bash
+        run: |
+          # Calculate the first day of the previous month
+          first_day=$(date -d "last month" +%Y-%m-01)
+
+          # Calculate the last day of the previous month
+          last_day=$(date -d "$first_day +1 month -1 day" +%Y-%m-%d)
+
+          #Set an environment variable with the date range
+          echo "$first_day..$last_day"
+          echo "last_month=$first_day..$last_day" >> "$GITHUB_ENV"
+
+      - name: Get issue metrics
+        uses: github/issue-metrics@v2
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SEARCH_QUERY: 'repo:owner/repo1 repo:owner/repo2 is:issue created:${{ env.last_month }} -reason:"not planned"'
+
+      - name: Create issue
+        uses: peter-evans/create-issue-from-file@v4
+        with:
+          title: Monthly issue metrics report (dev)
+          token: ${{ secrets.GITHUB_TOKEN }}
+          content-filepath: ./issue_metrics.md
+          assignees: <YOUR_GITHUB_HANDLE_HERE>
+```
+

docs/local-usage-without-docker.md

@@ -0,0 +1,8 @@
+## Local usage without Docker
+
+1. Make sure you have at least Python3.11 installed
+1. Copy `.env-example` to `.env`
+1. Fill out the `.env` file with a _token_ from a user that has access to the organization to scan (listed below). Tokens should have admin:org or read:org access.
+1. Fill out the `.env` file with the _search_query_ to filter issues by
+1. `pip3 install -r requirements.txt`
+1. Run `python3 ./issue_metrics.py`, which will output issue metrics data

docs/measure-time.md

@@ -0,0 +1,105 @@
+## Measuring time spent in labels
+
+**Note**: The discussions API currently doesn't support the `LabeledEvent` so this action cannot measure the time spent in a label for discussions.
+
+Sometimes it is helpful to know how long an issue or pull request spent in a particular label. This action can be configured to measure the time spent in a label. This is different from only wanting to measure issues with a specific label. If that is what you want, see the section on [configuring your search query](https://github.com/github/issue-metrics/blob/main/README.md#search_query-issues-or-pull-requests-open-or-closed).
+
+Here is an example workflow that does this:
+
+```yaml
+name: Monthly issue metrics
+on:
+  workflow_dispatch:
+
+permissions:
+  issues: write
+  pull-requests: read
+
+jobs:
+  build:
+    name: issue metrics
+    runs-on: ubuntu-latest
+
+    steps:
+
+    - name: Run issue-metrics tool
+      uses: github/issue-metrics@v2
+      env:
+        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        LABELS_TO_MEASURE: 'waiting-for-manager-approval,waiting-for-security-review'
+        SEARCH_QUERY: 'repo:owner/repo is:issue created:2023-05-01..2023-05-31 -reason:"not planned"'
+
+    - name: Create issue
+      uses: peter-evans/create-issue-from-file@v4
+      with:
+        title: Monthly issue metrics report
+        token: ${{ secrets.GITHUB_TOKEN }}
+        content-filepath: ./issue_metrics.md
+        assignees: <YOUR_GITHUB_HANDLE_HERE>
+
+```
+
+then the report will look like this:
+
+```markdown
+# Issue Metrics
+
+| Metric | Value |
+| --- | ---: |
+| Average time to first response | 0:50:44.666667 |
+| Average time to close | 6 days, 7:08:52 |
+| Average time to answer | 1 day |
+| Average time spent in waiting-for-manager-approval | 0:00:41 |
+| Average time spent in waiting-for-security-review | 2 days, 4:25:03 |
+| Number of items that remain open | 2 |
+| Number of items closed | 1 |
+| Total number of items created | 3 |
+
+| Title | URL | Time to first response | Time to close | Time to answer | Time spent in waiting-for-manager-approval | Time spent in waiting-for-security-review |
+| --- | --- | --- | --- | --- | --- | --- |
+| Pull Request Title 1 | https://github.com/user/repo/pulls/1 | 0:05:26 | None | None | None | None |
+| Issue Title 2 | https://github.com/user/repo/issues/2 | 2:26:07 | None | None | 0:00:41 | 2 days, 4:25:03 |
+
+```
+
+## Example issue_metrics.md output
+
+Here is the output with no hidden columns:
+```markdown
+# Issue Metrics
+
+| Metric | Value |
+| --- | ---: |
+| Average time to first response | 0:50:44.666667 |
+| Average time to close | 6 days, 7:08:52 |
+| Average time to answer | 1 day |
+| Number of items that remain open | 2 |
+| Number of items closed | 1 |
+| Total number of items created | 3 |
+
+| Title | URL | Time to first response | Time to close | Time to answer |
+| --- | --- | --- | --- | --- |
+| Discussion Title 1 | https://github.com/user/repo/discussions/1 | 0:00:41 | 6 days, 7:08:52 | 1 day |
+| Pull Request Title 2 | https://github.com/user/repo/pulls/2 | 0:05:26 | None | None |
+| Issue Title 3 | https://github.com/user/repo/issues/3 | 2:26:07 | None | None |
+
+```
+
+Here is the output with all hidable columns hidden:
+```markdown
+# Issue Metrics
+
+| Metric | Value |
+| --- | ---: |
+| Number of items that remain open | 2 |
+| Number of items closed | 1 |
+| Total number of items created | 3 |
+
+| Title | URL |
+| --- | --- |
+| Discussion Title 1 | https://github.com/user/repo/discussions/1 |
+| Pull Request Title 2 | https://github.com/user/repo/pulls/2 |
+| Issue Title 3 | https://github.com/user/repo/issues/3 |
+
+```
+