:pencil: TODOasIssue

workflow pubdev

Summary

  1. Description

  2. Installation

  3. Setting up todo.json

    3.1. Required fields for GitHub

    3.2. Required fields for GitLab

  4. Setting up todo.txt

  5. Usage

  6. Project architecture

  7. Supported platforms

  8. License

Description

From a list of TODOs to a list of issues on your GitHub or GitLab repository.

[~]: "This is my first TODO";
[]: "This is my second TODO";
[]: "This is my third TODO" "And it also has a body text";
[]: "This is my last TODO" "And it has a body text" {"label1", "label2"};

GitHub and Gitlab projects can have issues created by developers / users to report errors, bugs and etcetera. The idea of building TODOasIssue is to automate the creation of issues locally by writing everything that you need in a simple text file and publishing it to your GitHub / GitLab project without even opening your browser to do that.

Installation

First of all, you need to have Dart installed on your computer. See Dart documentation. After that, run the following command:

dart pub global activate todo_as_issue

Now you have TodoAsIssue installed.

Setting up todo.json

On your project root folder, create a file called todo.json and paste the content below:

{
  "owner": "YOUR_GITHUB_USERNAME",
  "repo_name_github": "YOUR_GITHUB_REPOSITORY_NAME",
  "repo_id_gitlab": "YOUR_GITLAB_PROJECT_ID",
  "platform": "YOUR_OPEN_SOURCE_PLATFORM",
  "github_token": "YOUR_PRIVATE_TOKEN_FROM_GITHUB",
  "gitlab_token": "YOUR_PRIVATE_TOKEN_FROM_GITLAB"
}

In platform field, you can use github or gitlab.

See the image below from my URL bar that will teach you how to identify your owner and repo_name_github fields:

image

After that, you can create a file called todo.txt in the project root folder to insert all your TODOs. For more informations and examples about how to create a TODO file, go here.

Required fields for GitHub

  • owner: Your GitHub username
  • repo_name_github: Your repository name
  • platform: It should be github
  • github_token: Your private access token. See GitHub Docs

Leave the remaining ones empty (empty string).

Required fields for GitLab

  • repo_id_gitlab: Your repository id
  • platform: It should be gitlab
  • gitlab_token: Your private access token. See GitLab Docs

You can leave the remaining one empty because each platform will only its required fields.

WARNING: Insert this file todo.json on your .gitignore in order to keep your informations safe, especially your private token.

Setting up todo.txt

In the description, you have a pretty clear example on how to structure your todo.txt. In this section I just want to mention a couple things.

First of all, each issue can have a title, body and a labels. title is required, but body and labels are not, however you need to respect the order. For example:

[]: "Title of issue" "Body of issue" {"label1", "label2"};

The example above is valid because labels are placed after body.

[]: "Title of issue" {"label1", "label2"} "Body of issue";

The example above is invalid because labels are placed before body. This order is wrong!

Usage

After setting up TodoAsIssue, go to your project's root directory and run the following command:

todo_as_issue

That command will look for todo.json and todo.txt on project's root directory.

Project architecture

Supported platforms

  • Linux: Working properly on Manjaro Arch Linux and Ubuntu.
  • Windows: It might work, but it was not tested.
  • macOS: It might work, but it was not tested.

License

This project is licensed under the MIT license. See LICENSE.

Libraries

api/api
api/github
api/gitlab
api/opensource_platform
api/successful_status
core/errors/api_exceptions
core/errors/lexer_exceptions
core/errors/parser_exceptions
core/http_client/http_client
core/http_client/http_client_interface
core/http_client/http_status
lexer/lexer
lexer/position
lexer/tokens
parser/issue
parser/parser
utils/configuration
utils/endpoints
utils/reader