todo_as_issue 1.0.1

A command-line interface for converting a TODO list into a list of issues on your GitHub / GitLab repository.

📝 TODOasIssue

Summary

1. Description
2. Installation
3. Usage
4. Project architecture
5. Design patterns used
6. License

Description

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

#(1)[~]: "This is my first TODO"
#(2)[]: "This is my second TODO"

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, 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.

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.

TODOasIssue must have these informations to make things work.

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

Usage

If everything above is configured, you're allowed to run the program. If you're not understanding the usage of [] or [~], it is just a mark for checking if the TODO was posted or not on GitHub / GitLab. If it is marked, then it is gonna be ignored by TodoAsIssue, it is useful to avoid duplicated issues.

Project architecture

• lib/api: Code that is related to the API's communication.
  • lib/api/api.dart: Class for calling method to create issues
  • lib/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.
  • lib/api/opensource_platform.dart: Interface for any open source platform that I may want to create in the future.
• lib/core: Code that is common across all the source code.
  • lib/core/http_client: Implementation of an HTTP client
    • lib/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 dependent
    • lib/core/http_client/http_client.dart: Implementation of an HTTP Client using http package.
• lib/lexer: Tool for converting a text file into a list of tokens
  • lib/lexer/lexer.dart: Implementation of lexer (tokenizer)
  • lib/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 TODOs
  • lib/parser/error_reporter.dart: Class for simply reporting a parsing error (every time a todo file is not formatted, this class should throw an error and close the program).
  • lib/parser/parser.dart: Class for converting a list of tokens (generated by the lexer) into a list of TODOs
  • lib/parser/todo.dart: Class for representing a TODO object.
• lib/utils: Utility code
  • lib/utils/configuration.dart: Data class for representing todo.json.
  • lib/utils/endpoints.dart: Important endpoints
  • lib/utils/reader.dart: Helper class for reading importants files (todo.json and todo.txt)

Design patterns used

• Iterator

  Iterator pattern was used on the parser implementation. I used it for iterating over a list of tokens. Additionally, even though Dart provides a built-in iterator for List, Dart doesn't offer me a method called hasNext() to check if there is a next element to iterate, that's why I implemented this pattern, just for building this method by myself. You can check it out here.

• Singleton

  Singleton pattern was used on the implementation of open source platforms, such as GitHub and GitLab. I decided to use it because I didn't want to have more than one instance of each platform on my program, it should be unique, makes no sense to have more than one of these. You can check it out here and here.

• Strategy

  Strategy pattern was used on the implementation of open source platforms as well. I decided to do this because we can have more than one kind of open source platforms, such as GitHub and GitLab. Therefore we can change the "strategy" to another open source platform. You can check it out here.

• Facade

  Facade pattern was used on the implementation of TodoAsIssue class. This class is used for calling all the important methods, just acting like an front-facing interface masking more complex underlying code. It happens because TodoAsIssue doesn't know anything about the inner implementations of lexer and parser, for example, that's why it is called "Facade". You can check it out here.

License

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