Merge pull request #26 from siisurit/13-clean-up-implementation

#13 Clean up implementation

data/.check_done.yaml → .check_done.yaml

@@ -1,3 +1,5 @@
 project_url: ${CHECK_DONE_GITHUB_PROJECT_URL}
+project_status_name_to_check: ${CHECK_DONE_GITHUB_PROJECT_STATUS_NAME_TO_CHECK}
+personal_access_token: ${CHECK_DONE_PERSONAL_ACCESS_TOKEN}
 check_done_github_app_id: ${CHECK_DONE_GITHUB_APP_ID}
 check_done_github_app_private_key: ${CHECK_DONE_GITHUB_APP_PRIVATE_KEY}

.github/workflows/build.yml

@@ -42,13 +42,16 @@ jobs:
           CHECK_DONE_GITHUB_APP_ID: ${{ secrets.CHECK_DONE_GITHUB_APP_ID }}
           CHECK_DONE_GITHUB_APP_PRIVATE_KEY: |
             ${{ secrets.CHECK_DONE_GITHUB_APP_PRIVATE_KEY }}
+          CHECK_DONE_GITHUB_PROJECT_STATUS_NAME_TO_CHECK: ${{ secrets.CHECK_DONE_GITHUB_PROJECT_STATUS_NAME_TO_CHECK }}
+          CHECK_DONE_PERSONAL_ACCESS_TOKEN: ${{ secrets.CHECK_DONE_PERSONAL_ACCESS_TOKEN }}
+          CHECK_DONE_USER_GITHUB_PROJECT_URL: ${{ secrets.CHECK_DONE_USER_GITHUB_PROJECT_URL }}
         run: |
-          poetry run pytest --cov=check-done --cov-branch
+          poetry run pytest --cov=check_done --cov-branch
 
   check-style:
     runs-on: ubuntu-latest
     # Disable pre-commit check on main and production to prevent
-    # pull request merges to fail with don't commit to branch".
+    # pull request merges to fail with don't commit to branch.
     if: github.ref != 'refs/heads/main'
     steps:
       - uses: actions/checkout@v3

.gitignore

@@ -287,4 +287,6 @@ poetry.toml
 # LSP config files
 pyrightconfig.json
 
+/.idea/ruff.xml
+
 # End of https://www.toptal.com/developers/gitignore/api/pycharm,python

.license-in-code

@@ -0,0 +1,2 @@
+Copyright (C) 2024 by Siisurit e.U., Austria.
+All rights reserved. Distributed under the MIT License.

.pre-commit-config.yaml

@@ -2,7 +2,7 @@ exclude: "^\\.idea"
 
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.6.8
+    rev: v0.7.4
     hooks:
       - id: ruff-format
       - id: ruff
@@ -14,7 +14,7 @@ repos:
       - id: prettier
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
       - id: fix-byte-order-marker
       - id: trailing-whitespace
@@ -31,11 +31,24 @@ repos:
       - id: end-of-file-fixer
       - id: mixed-line-ending
 
+  - repo: https://github.com/Lucas-C/pre-commit-hooks
+    rev: v1.5.5
+    hooks:
+      - id: insert-license
+        files: \.py$
+        args:
+          - --license-filepath=.license-in-code
+          - --comment-style=#
+          - --detect-license-in-X-top-lines=2
+          - --no-extra-eol
+          - --allow-past-years # Using these arguments allows for a date range
+          - --use-current-year # (original_date - current_date) to be generated.
+
   # NOTE: This should be the last check to ensure everything else is checked
   #  even for the rare case a commit should go into one of the protected
   #  branches.
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
       - id: no-commit-to-branch
         args: ["--branch", "main"]

README.md

@@ -1,3 +1,78 @@
 # check_done
 
-Check done issues on a GitHub project board.
+check_done is a command line tool to check that finished issues and pull requests in a GitHub project board column are really done.
+
+## Configuration
+
+To use check_done for your project, you need to configure the fields in the `yaml` file found in the `configuration` folder.
+
+### General settings
+
+#### project_url (required)
+
+The project URL as is when viewing your GitHub V2 project. E.g.: `"https://github.com/orgs/my_project_owner_name/projects/1/views/1"`
+
+#### project_status_name_to_check (optional)
+
+By default, check_done checks all issues and pull requests in the column rightmost / last column of the project board. If you left the default names when creating the GitHub project board, this will be the `"✅ Done"` column.
+
+If you want to check a different column, you can specify its name with this option. For example:
+
+```yaml
+project_status_name_to_check = "Done"
+```
+
+The name takes the first column that partially matches case sensitively. For example, `"Done"` will also match `"✅ Done"`, but not `"done"`.
+
+If no column matches, the resulting error messages will tell you the exact names of all available columns.
+
+### Authorization settings for a project belonging to a GitHub user
+
+#### personal_access_token
+
+A personal access token with the permission: `read:project`.
+
+Example:
+
+```yaml
+project_url: "https://github.com/orgs/my_username/projects/1/views/1"
+personal_access_token: "ghp_xxxxxxxxxxxxxxxxxxxxxx"
+# Since no `project_status_name_to_check` was specified, the checks will apply to the last project status/column.
+```
+
+### Authorization settings for a project belonging to a GitHub organization
+
+Follow the instructions to [Installing a GitHub App from a third party](https://docs.github.com/en/apps/using-github-apps/installing-a-github-app-from-a-third-party) using the [Siisurit's check_done app](https://github.com/apps/siisurit-s-check-done).
+
+You can also derive your own GitHub app from it with the following permissions:
+
+- `pull requests`
+- `projects`
+- `read:issues`
+
+Remember the App ID and the app private key. Then add the following settings to the configuration file:
+
+```yaml
+check_done_github_app_id = ...  # Typically a decimal number with at least 6 digits
+check_done_github_app_private_key = ""-----BEGIN RSA PRIVATE KEY..."
+```
+
+Example:
+
+```yaml
+project_url: "https://github.com/orgs/my_username/projects/1/views/1"
+check_done_github_app_id: "0123456"
+check_done_github_app_private_key: "-----BEGIN RSA PRIVATE KEY-----
+something_something
+-----END RSA PRIVATE KEY-----
+"
+project_status_name_to_check: "Done" # This will match the name of a project status/column containing "Done" like "✅ Done". The checks will then be applied to this project status/column.
+```
+
+### Using environment variables and examples
+
+You can use environment variables for the values in the configuration yaml by starting them with a `$` symbol and wrapping it with curly braces. For example:
+
+```yaml
+personal_access_token: ${MY_PERSONAL_ACCESS_TOKEN_ENVVAR}
+```

check_done/__init__.py

@@ -0,0 +1,5 @@
+# Copyright (C) 2024 by Siisurit e.U., Austria.
+# All rights reserved. Distributed under the MIT License.
+from importlib.metadata import version
+
+__version__ = version(__name__)