todo_as_issue 1.3.3 todo_as_issue: ^1.3.3 copied to clipboard
A command-line interface for converting a TODO list into a list of issues on your GitHub / GitLab repository.
📝 TODOasIssue #
Summary #
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:
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 usernamerepo_name_github
: Your repository nameplatform
: It should begithub
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 idplatform
: It should begitlab
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 #
lib/api
: Code that is related to the API's communication.lib/api/api.dart
: Class for calling method to create issueslib/api/github.dart
: Class for implementing the communication with GitHub's API to create an issue.lib/api/gitlab.dart
: Class for implementing the communication with GitLab's API to create an issue. Extracting some methods on API communication code -lib/api/opensource_platform.dart
: Interface for any open source platform that I may want to create in the future../lib/api/successful_status.dart
: Class for getting successful message based on issue counter.
lib/core
: Code that is common across all the source code.lib/core/http_client
: Implementation of an HTTP clientlib/core/http_client/http_client_interface.dart
: Interface for any HTTP client that I may want to create in the future. This is useful because my code will not be dependentlib/core/http_client/http_client.dart
: Implementation of an HTTP Client usinghttp
package.lib/core/http_client/http_status.dart
: An enum for representing different types of HTTP status code.
lib/core/errors
:lib/core/errors/api_exceptions
: File for defining all exceptions related to API communication.lib/core/errors/lexer_exceptions.dart
: File for defining all exceptions related to the lexer.lib/core/errors/parser_exceptions.dart
: File for defining all exceptions related to the parser.
lib/lexer
: Tool for converting a text file into a list of tokenslib/lexer/lexer.dart
: Implementation of lexer (tokenizer)lib/lexer/position.dart
: Class for managing cursor and line positionslib/lexer/tokens.dart
: Class for representing a token and an enum to represent a token kind.
lib/parser
: Tool for converting a list of tokens into a list of TODOslib/parser/parser.dart
: Class for converting a list of tokens (generated by the lexer) into a list of TODOslib/parser/issue.dart
: Class for representing an issue object.
lib/utils
: Utility codelib/utils/configuration.dart
: Data class for representingtodo.json
.lib/utils/endpoints.dart
: Important endpointslib/utils/reader.dart
: Helper class for reading importants files (todo.json
andtodo.txt
)
test
: Folder for storing all teststest/mocks/
: Folder for defining some mocks for helping me to test the code.test/mocks/configuration_mock.dart
: File for storing a mock object ofConfiguration
.test/mocks/todo_mocks.dart
: File for storing a list of mock TODOs.
test/api_test.dart
: Unit test for API communication.test/lexer_test.dart
: Unit test for lexertest/parser_test.dart
: Unit test for parser
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.