Skip to content

Commit

Permalink
Clarify optional input documentation
Browse files Browse the repository at this point in the history 
After a bit of trial and error, I gather that the workflow API must only provide strings as input. QED, the optional inputs have to be strings. Not a big deal, except for the `IDENTIFIERS` value which needs to be a JSON string, which looks exactly like a YAML sequence. Updated documentation to include what I needed to see to resolve this.
  • Loading branch information
Seth Battis authored and Seth Battis committed Oct 28, 2022
1 parent fe135b9 commit ffe68fc
Showing 1 changed file with 103 additions and 90 deletions.
193 changes: 103 additions & 90 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,83 +31,97 @@ Multiline TODOs are supported, with additional lines inserted into the issue bod
Create a `workflow.yml` file in your `.github/workflows` directory like:

```yml
name: "Run TODO to Issue"
on: ["push"]
jobs:
build:
name: "Run TODO to Issue"
on: ["push"]
jobs:
build:
runs-on: "ubuntu-latest"
steps:
- uses: "actions/checkout@v3"
- name: "TODO to Issue"
uses: "alstr/todo-to-issue-action@v4"
- uses: "actions/checkout@v3"
- name: "TODO to Issue"
uses: "alstr/todo-to-issue-action@v4"
```
See [Github's workflow syntax](https://help.github.com/en/actions/reference/workflow-syntax-for-github-actions) for further details on this file.
The workflow file takes the following optional inputs:
| Input | Required | Description |
|------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `CLOSE_ISSUES` | No | Optional boolean input that specifies whether to attempt to close an issue when a TODO is removed. Default: `true`. |
| `AUTO_P` | No | Optional boolean input that specifies whether to format each line in multiline TODOs as a new paragraph. Default: `true`. |
| `IGNORE` | No | Optional string input that provides comma-delimited regular expressions that match files in the repo that we should not scan for TODOs. By default, we will scan all files. |
| `AUTO_ASSIGN` | No | Optional boolean input that specifies whether to assign the newly created issue to the user who triggered the action. If users are manually assigned to an issue, this setting is ignored. Default: `false`. |
| `ISSUE_TEMPLATE` | No | You can override the default issue template by providing your own here. Markdown is supported, and you can inject the issue title, body, code URL and snippet. Example: `"This is my issue title: **{{ title }}**\n\nThis is my issue body: **{{ body }}**\n\nThis is my code URL: **{{ url }}**\n\nThis is my snippet:\n\n{{ snippet }}"` |
| `IDENTIFIERS` | No | A list of dictionaries specifying the identifiers for the action to recognise. `TODO` is the default, but you can override this here, and specify default labels to be applied when creating issues for each identifier. JSON must be valid with double quoted keys/values. Example: `[{"name": "TODO", "labels": ["help wanted"]}, {"name": "FIXME", "labels": ["bug"]}]` (`labels` should be an empty list if no default labels are wanted) |
| Input | Required | Description |
| ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CLOSE_ISSUES` | No | Optional boolean input that specifies whether to attempt to close an issue when a TODO is removed. Default: `true`. |
| `AUTO_P` | No | Optional boolean input that specifies whether to format each line in multiline TODOs as a new paragraph. Default: `true`. |
| `IGNORE` | No | Optional string input that provides comma-delimited regular expressions that match files in the repo that we should not scan for TODOs. By default, we will scan all files. |
| `AUTO_ASSIGN` | No | Optional boolean input that specifies whether to assign the newly created issue to the user who triggered the action. If users are manually assigned to an issue, this setting is ignored. Default: `false`. |
| `ISSUE_TEMPLATE` | No | You can override the default issue template by providing your own here. Markdown is supported, and you can inject the issue title, body, code URL and snippet. Example: `"This is my issue title: **{{ title }}**\n\nThis is my issue body: **{{ body }}**\n\nThis is my code URL: **{{ url }}**\n\nThis is my snippet:\n\n{{ snippet }}"` |
| `IDENTIFIERS` | No | A list of dictionaries specifying the identifiers for the action to recognise. `TODO` is the default, but you can override this here, and specify default labels to be applied when creating issues for each identifier. JSON string must be valid with double quoted keys/values. Example: `"[{\"name\": \"TODO\", \"labels\": [\"help wanted\"]}, {\"name\": \"FIXME\", \"labels\": [\"bug\"]}]"` (`labels` should be an empty list if no default labels are wanted) |

These can be specified in `with` in the workflow file, as below:

These can be specified in `with` in the workflow file.
```yml
name: "Run TODO to Issue"
on: ["push"]
jobs:
build:
runs-on: "ubuntu-latest"
steps:
- uses: "actions/checkout@v3"
- name: "TODO to Issue"
uses: "alstr/todo-to-issue-action@v4"
with:
AUTO_ASSIGN: true
```

### Considerations

* TODOs are found by analysing the difference between the new commit and its previous one (i.e., the diff). That means that if this action is implemented during development, any existing TODOs will not be detected. For them to be detected, you would have to remove them, commit, put them back, and commit again, or [run the action manually](#running-the-action-manually).
* Should you change the TODO text, this will currently create a new issue.
* Closing TODOs is still somewhat experimental.
- TODOs are found by analysing the difference between the new commit and its previous one (i.e., the diff). That means that if this action is implemented during development, any existing TODOs will not be detected. For them to be detected, you would have to remove them, commit, put them back, and commit again, or [run the action manually](#running-the-action-manually).
- Should you change the TODO text, this will currently create a new issue.
- Closing TODOs is still somewhat experimental.

## Supported Languages

* ABAP
* ABAP CDS
* AutoHotkey
* C
* C++
* C#
* CSS
* Crystal
* Clojure
* Dart
* Elixir
* Go
* Handlebars
* HCL
* Haskell
* HTML
* Java
* JavaScript
* JSON5
* Julia
* Kotlin
* Less
* Markdown
* Objective-C
* Org Mode
* PHP
* Python
* R
* Razor
* Ruby
* Rust
* Sass
* Scala
* SCSS
* Shell
* SQL
* Swift
* TeX
* TSX
* Twig
* TypeScript
* Vue
* YAML
- ABAP
- ABAP CDS
- AutoHotkey
- C
- C++
- C#
- CSS
- Crystal
- Clojure
- Dart
- Elixir
- Go
- Handlebars
- HCL
- Haskell
- HTML
- Java
- JavaScript
- JSON5
- Julia
- Kotlin
- Less
- Markdown
- Objective-C
- Org Mode
- PHP
- Python
- R
- Razor
- Ruby
- Rust
- Sass
- Scala
- SCSS
- Shell
- SQL
- Swift
- TeX
- TSX
- Twig
- TypeScript
- Vue
- YAML

New languages can easily be added to the `syntax.json` file used by the action to identify TODO comments. When adding languages, follow the structure of existing entries, and use the language name defined by GitHub in [`languages.yml`](https://raw.githubusercontent.com/github/linguist/master/lib/linguist/languages.yml). PRs adding new languages are welcome and appreciated. Please add a test for your language in order for your PR to be accepted. See [Contributing](#contributing--issues).

Expand Down Expand Up @@ -143,7 +157,7 @@ Don't include parentheses within the identifier itself.

### Projects

*Please note, the action currently only supports classic user and organisation projects, and not 'new' projects.*
_Please note, the action currently only supports classic user and organisation projects, and not 'new' projects._

You can assign the created issue to columns within user or organisation projects with some additional setup.

Expand Down Expand Up @@ -175,27 +189,25 @@ You can run the action manually by adding support for the `workflow_dispatch` ev
```yaml
name: "Run TODO to Issue"
on:
push:
workflow_dispatch:
inputs:
MANUAL_COMMIT_REF:
description: "The SHA of the commit to get the diff for"
required: true
MANUAL_BASE_REF:
description: "By default, the commit entered above is compared to the one directly before it; to go back further, enter an earlier SHA here"
required: false
push:
workflow_dispatch:
inputs:
MANUAL_COMMIT_REF:
description: "The SHA of the commit to get the diff for"
required: true
MANUAL_BASE_REF:
description: "By default, the commit entered above is compared to the one directly before it; to go back further, enter an earlier SHA here"
required: false
jobs:
build:
runs-on: "ubuntu-latest"
steps:
- uses: "actions/checkout@v3"
- name: "TODO to Issue"
uses: "alstr/todo-to-issue-action@master"
env:
MANUAL_COMMIT_REF:
${{ inputs.MANUAL_COMMIT_REF }}
MANUAL_BASE_REF:
${{ inputs.MANUAL_BASE_REF }}
build:
runs-on: "ubuntu-latest"
steps:
- uses: "actions/checkout@v3"
- name: "TODO to Issue"
uses: "alstr/todo-to-issue-action@master"
env:
MANUAL_COMMIT_REF: ${{ inputs.MANUAL_COMMIT_REF }}
MANUAL_BASE_REF: ${{ inputs.MANUAL_BASE_REF }}
```

Head to the Actions section of your repo, select the workflow and then 'Run workflow'.
Expand All @@ -208,10 +220,10 @@ You can also compare a broader range of commits. In this case, also enter the 'f

### No issues have been created

* Make sure your file language is in `syntax.json`.
* The action will not recognise existing TODOs that have already been pushed, unless you [run the action manually](#running-the-action-manually).
* If a similar TODO appears in the diff as both an addition and deletion, it is assumed to have been moved, so is ignored.
* If your workflow is executed but no issue is generated, check your repo permissions by navigating to `Settings -> Actions (General) -> Workflow permissions` and enable "Read and write permissions".
- Make sure your file language is in `syntax.json`.
- The action will not recognise existing TODOs that have already been pushed, unless you [run the action manually](#running-the-action-manually).
- If a similar TODO appears in the diff as both an addition and deletion, it is assumed to have been moved, so is ignored.
- If your workflow is executed but no issue is generated, check your repo permissions by navigating to `Settings -> Actions (General) -> Workflow permissions` and enable "Read and write permissions".

### Multiple issues have been created

Expand All @@ -226,6 +238,7 @@ If you do encounter any problems, please file an issue or submit a PR. Everyone
## Running tests locally

To run the tests locally, simply run the following in the main repo:

```shell
python -m unittest
```
Expand All @@ -234,9 +247,9 @@ python -m unittest

If you want to fork this action to customise its behaviour, there are a few steps you should take to ensure your changes run:

* In `workflow.yml`, set `uses: ` to your action.
* In `action.yml`, set `image: ` to `Dockerfile`, rather than the prebuilt image.
* If customising `syntax.json`, you will want to update the URL in `main.py` to target your version of the file.
- In `workflow.yml`, set `uses: ` to your action.
- In `action.yml`, set `image: ` to `Dockerfile`, rather than the prebuilt image.
- If customising `syntax.json`, you will want to update the URL in `main.py` to target your version of the file.

## Thanks

Expand Down

0 comments on commit ffe68fc

Please sign in to comment.