Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Implement custom clippy rule to track TODOs #556

Open
minikin opened this issue Sep 7, 2023 · 2 comments
Open

Implement custom clippy rule to track TODOs #556

minikin opened this issue Sep 7, 2023 · 2 comments
Assignees
Labels
enhancement New feature or request

Comments

@minikin
Copy link
Collaborator

minikin commented Sep 7, 2023

Create a custom Clippy lint that checks for the specific TODO format TODO(username): message, URL where the URL can be a GitHub or Jira issue.

Purpose

Ensure that TODO comments in the codebase adhere to a standard format:
TODO(username): message, URL. The URL should link to a GitHub or Jira issue.

Lint Description

Warns when encountering a TODO comment that does not match the following format:

TODO(username): message, URL

Where:

username is a placeholder for the developer's username.
message is a short description of the TODO.
URL is a link to a GitHub or Jira issue.

Criteria

The lint should consider a comment as a valid TODO format if:

  • The comment starts with the string TODO(.
  • The comment contains a ): following the TODO(. The enclosed value should be considered the username.
  • After the ):, there should be a brief message.
  • After the message, there should be a comma , followed by a space.
  • The comment ends with a URL. The URL should start with https:// and should link to either a GitHub issue (github.com/owner/repo/issues/number) or a Jira issue (typically company-name.atlassian.net/browse/ISSUE-ID).

Non-Criteria

  • The lint should not enforce any specific length or content constraints for the message part, as long as it's followed by a,
    and a space.
  • The lint should not enforce the validity of the URL, only its format.

Examples

Valid TODOs

// TODO(john_doe): Implement the authentication module, https://github.com/myrepo/myproject/issues/123
// TODO(jane_doe): Refactor the function for clarity, https://company-name.atlassian.net/browse/BUG-456

Invalid TODOs

// TODO: Implement this!
// TODO(john_doe) Fix this issue.
// TODO(jane_doe): This needs to be fixed, myproject/issues/123

Output Message

Found TODO comment that doesn't adhere to the standard format:

TODO(username): message, URL.` Please include the developer's username and a link to a GitHub or Jira issue.

Implementation Notes

  • Regular expressions could be used to match the specific format.
  • The lint should look for comments starting with TODO( to minimize unnecessary parsing.

Additional Considerations:

  • Consider expanding the lint to support other popular issue trackers in the future.
  • Consider implementing a method to verify the URL is validity (but be cautious about accidentally making web requests).
@minikin
Copy link
Collaborator Author

minikin commented Sep 7, 2023

@Mr-Leshiy @FelipeRosa @saibatizoku @cong-or @stevenj @nicopado @kukkok3 your feedback is very welcome.

@minikin minikin added the enhancement New feature or request label Sep 7, 2023
@stevenj
Copy link
Collaborator

stevenj commented Sep 7, 2023

This is a great idea.

I would say that the URL should always be a github issue if the repo is public. And if there is a jira issue it can be linked to from the github issue.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

2 participants