diff --git a/README.md b/README.md index 2865600..7e0910e 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,24 @@ # TODO to Issue Action -This action will convert newly committed TODO comments to GitHub issues on push. It will also optionally close the issues if the TODOs are removed in a future commit. +This action will convert newly committed TODO comments to GitHub issues on push. -TODO to Issue works with almost any programming language. +Optionally, issues can also be closed when the TODOs are removed in a future commit. + +Action supports: + +* Multiple, customizable comments identifiers (FIXME, etc.), +* Configurable auto-labeling, +* Assignees, +* Milestones, +* Projects (classic). + +`todo-to-issue` works with almost any programming language. ## Usage -Simply add a comment starting with TODO, followed by a colon and/or space. Here's an example for Python that creates an issue named after the TODO: +Simply add a comment starting with TODO (or any other comment identifiers configured), followed by a colon and/or space. + +Here's an example for Python creating an issue named after the TODO _description_: ```python def hello_world(): @@ -14,59 +26,91 @@ Simply add a comment starting with TODO, followed by a colon and/or space. Here' print('Hello world!') ``` -Multiline TODOs are supported, with additional lines inserted into the issue body. A range of options can also be provided to apply to the new issue: +_Multiline_ TODOs are supported, with additional lines inserted into the issue body: ```python def hello_world(): - # TODO Come up with a more imaginative greeting + # TODO: Come up with a more imaginative greeting # Everyone uses hello world and it's boring. - # labels: enhancement, help wanted - # assignees: alstr, bouteillerAlan, hbjydev - # milestone: 1 print('Hello world!') ``` -## TODO Options - -Unless specified otherwise, options should be on their own line, below the initial TODO declaration. - -### `assignees:` - -Comma-separated list of usernames to assign to the issue. - -### `labels:` - -Comma-separated list of labels to add to the issue. If any of the labels do not already exist, they will be created. The `todo` label is automatically added to issues to help the action efficiently retrieve them in the future. - -### `milestone:` - -Milestone ID to assign to the issue. Only a single milestone can be specified and this must already have been created. - -## Other Options - -### Reference - -As per the [Google Style Guide](https://google.github.io/styleguide/cppguide.html#TODO_Comments), you can provide a reference after the TODO label. This will be included in the issue title for searchability. +As per the [Google Style Guide](https://google.github.io/styleguide/cppguide.html#TODO_Comments), you can provide a _reference_ after the TODO identifier. This will be included in the issue title for searchability. ```python def hello_world(): # TODO(alstr) Come up with a more imaginative greeting + # Everyone uses hello world and it's boring. print('Hello world!') ``` -Don't include parentheses within the identifier itself. +Don't include parentheses within the reference itself. + +## TODO Options + +A range of options can also be provided to apply to the new issue. + +Options follow the `name: value` syntax. +Unless otherwise specified, options should be on their own line, below the initial TODO declaration and 'body'. + +### Assignees + +Comma-separated list of usernames to assign to the issue: + +```python + def hello_world(): + # TODO(alstr): Come up with a more imaginative greeting + # Everyone uses hello world and it's boring. + # assignees: alstr, bouteillerAlan, hbjydev + print('Hello world!') +``` + +### Labels + +Comma-separated list of labels to add to the issue: + +```python + def hello_world(): + # TODO(alstr): Come up with a more imaginative greeting + # Everyone uses hello world and it's boring. + # labels: enhancement, help wanted + print('Hello world!') +``` + +If any of the labels do not already exist, they will be created. + +The `todo` label is automatically added to issues to help the action efficiently retrieve them in the future. + +### Milestone + +Milestone `ID` to assign to the issue: + +```python + def hello_world(): + # TODO(alstr): Come up with a more imaginative greeting + # Everyone uses hello world and it's boring. + # milestone: 1 + print('Hello world!') +``` + +Only a single milestone can be specified and it must already exist. ### 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. +With some additional setup, you can assign the created issues a status (column) within user or organisation projects. -The action cannot access your projects by default. To enable access, you must [create an encrypted secret in your repo settings](https://docs.github.com/en/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository), with the value set to a valid Personal Access Token. Then, assign the secret in the workflow file like `PROJECTS_SECRET: ${{ secrets.PROJECTS_SECRET }}`. Do not enter the raw secret. +By default, the action cannot access your projects. To enable it, you must: -To assign to a user project, use the `user projects:` prefix. To assign to an organisation project, use `org projects:` prefix. +* [Create a Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token), +* [Create an encrypted secret in your repo settings](https://docs.github.com/en/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository), with the value set to the Personal Access Token, +* Assign the secret in the workflow file like `PROJECTS_SECRET: ${{ secrets.PROJECTS_SECRET }}`. _Do not enter the raw secret_. -The syntax is `/project name/column name`. All three must be provided. +Projects are identified by their `full project name and issue status` (column) reference with the `/project name/status name` syntax. + +* To assign to a _user project_, use the `user projects:` option. +* To assign to an _organisation project_, use `org projects:` option. ```python def hello_world(): @@ -77,9 +121,10 @@ The syntax is `/project name/column name`. All three must be p print('Hello world!') ``` -You can assign to multiple projects by using commas, for example: `user projects: alstr/Test User Project 1/To Do, alstr/Test User Project 2/Tasks`. +You can assign issues to multiple projects separating them with commas, i.e. `user projects: alstr/Test User Project 1/To Do, alstr/Test User Project 2/Tasks`. -You can also specify default projects in the same way by defining `USER_PROJECTS` or `ORG_PROJECTS` in your workflow file. These will be applied automatically to every issue, but will be overrode by any specified within the TODO. +You can also specify `default projects` in the same way by defining `USER_PROJECTS` or `ORG_PROJECTS` in your workflow file. +These will be applied automatically to every issue, but will be overrode by any specified within the TODO. ## Supported Languages @@ -130,7 +175,11 @@ You can also specify default projects in the same way by defining `USER_PROJECTS - XML - 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). +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). + +Of course, 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). ## Setup @@ -161,7 +210,7 @@ The workflow file takes the following optional inputs: | `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 and itself single-quoted (or double-quoted and escaped). 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 using `with` parameter in the workflow file, as below: ```yml name: "Run TODO to Issue" @@ -215,9 +264,9 @@ jobs: Head to the Actions section of your repo, select the workflow and then 'Run workflow'. -You can run the workflow for a single commit, whereby the action will compare the commit to the one directly before it. Enter the commit SHA in the first box. +You can run the workflow for a single commit by entering the commit SHA in the first box. In this case, the action will compare the commit to the one directly before it. -You can also compare a broader range of commits. In this case, also enter the 'from'/base commit SHA in the second box. +You can also compare a broader range of commits. For that, also enter the 'from'/base commit SHA in the second box. ## Troubleshooting