{"id":18151391,"url":"https://github.com/ihepda/java-tech-debt","last_synced_at":"2026-02-03T07:33:48.908Z","repository":{"id":258602148,"uuid":"874116483","full_name":"ihepda/java-tech-debt","owner":"ihepda","description":"The java-tech-debt project is an annotation and reporting tool designed to identify and manage technical debts in code.","archived":false,"fork":false,"pushed_at":"2025-02-04T08:01:25.000Z","size":173,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-07T18:58:19.345Z","etag":null,"topics":["java","maven","reporting","technical-debt"],"latest_commit_sha":null,"homepage":"https://ihepda.github.io/java-tech-debt/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ihepda.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-17T09:27:57.000Z","updated_at":"2025-02-04T08:01:27.000Z","dependencies_parsed_at":"2024-10-24T19:18:02.602Z","dependency_job_id":"57fa495a-56d4-4a6b-be09-f2bca97517fd","html_url":"https://github.com/ihepda/java-tech-debt","commit_stats":null,"previous_names":["ihepda/java-tech-debt"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/ihepda/java-tech-debt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ihepda%2Fjava-tech-debt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ihepda%2Fjava-tech-debt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ihepda%2Fjava-tech-debt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ihepda%2Fjava-tech-debt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ihepda","download_url":"https://codeload.github.com/ihepda/java-tech-debt/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ihepda%2Fjava-tech-debt/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29037528,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-03T06:39:36.383Z","status":"ssl_error","status_checked_at":"2026-02-03T06:39:32.787Z","response_time":96,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","maven","reporting","technical-debt"],"created_at":"2024-11-02T01:07:32.992Z","updated_at":"2026-02-03T07:33:48.887Z","avatar_url":"https://github.com/ihepda.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# java-tech-debt\n\n| Resource | Status |\n| ---- | ------ |\n|Parent project|[![Maven Central parent](https://maven-badges.herokuapp.com/maven-central/io.github.ihepda/tech-debt-parent/badge.svg?style=flat)](https://central.sonatype.com/artifact/io.github.ihepda/tech-debt-parent)|\n|Annotation project|[![Maven Central parent](https://maven-badges.herokuapp.com/maven-central/io.github.ihepda/tech-debt-annotation/badge.svg?style=flat)](https://central.sonatype.com/artifact/io.github.ihepda/tech-debt-annotation)|\n|Processor project|[![Maven Central parent](https://maven-badges.herokuapp.com/maven-central/io.github.ihepda/tech-debt-processor/badge.svg?style=flat)](https://central.sonatype.com/artifact/io.github.ihepda/tech-debt-processor)|\n|Maven plugin project|[![Maven Central parent](https://maven-badges.herokuapp.com/maven-central/io.github.ihepda/tech-debt-maven-plugin/badge.svg?style=flat)](https://central.sonatype.com/artifact/io.github.ihepda/tech-debt-maven-plugin)|\n\nThe *java-tech-debt* project is an annotation and reporting tool designed to identify and manage technical debts in code. Technical debts are an inevitable reality in software development, often overlooked or forgotten over time.\n\n## Why Technical Debts Matter\n\nTechnical debts represent compromises in the code that, if unmanaged, can lead to maintenance and scalability issues. Often, these debts are noted in external tools like Jira or ClickUp, but other times they are completely forgotten, accumulating and further complicating the development process.\n\n## Project Features\n\n* **Annotations**: Allows marking parts of the code that contain technical debts.\n* **Reporting**: Generates detailed reports to monitor and manage technical debts over time.\n\n## Conclusion\n\nThe java-tech-debt project offers an effective solution to keep code clean and manageable, helping development teams track technical debts and plan refactoring efforts in a more structured and informed way.\n\nAnnotating technical debts directly in the code with **java-tech-debt** helps keep the code clean and manageable. Following these steps will allow you to track technical debts and plan refactoring efforts in a more structured way.\n\n## Marking Technical Debts with java-tech-debt\n\n### Introduction\n\nThe **java-tech-debt** project allows you to annotate and manage technical debts directly in your code. This tutorial will guide you through the steps needed to mark technical debts using the annotations provided by the project.\n\n### Step 1: Add the Maven Dependency\n\nEnsure you have the **java-tech-debt** dependency in your *pom.xml* file:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.github.ihepda\u003c/groupId\u003e\n    \u003cartifactId\u003etech-debt-annotation\u003c/artifactId\u003e\n    \u003cversion\u003e1.0.1\u003c/version\u003e\n    \u003cscope\u003ecompile\u003c/scope\u003e\n    \u003coptional\u003etrue\u003c/optional\u003e\n\u003c/dependency\u003e\n```\n\nRemember to set the scope to **compile** and the **optional** tag to true. This configuration will use this library only in compilation phase and it won't be added as runtime dependency.\n\n### Step 2: Import the Annotation\n\nIn your Java file, import the necessary annotation:\n\n import io.github.ihepda.techdebt.annotations.TechDebt;\n\n### Step 3: Annotate the Code with Technical Debts\n\nUse the annotation to mark technical debts in your code. Here is an example:\n\n```java\n@TechDebt(\n    description = \"Refactor this method to improve readability\",\n    date = \"2024-10-28\",\n    owner = \"developer@example.com\",\n    severity= Severity.MAJOR\n)\npublic void someMethod() {\n    // Code that needs refactoring\n}\n```\n\nYou can use a single annotation or multiple annotation\n\n```java\n@TechDebt(severity = Severity.MAJOR, comment = \"classe\")\n@TechDebt(severity = Severity.MINOR, comment = \"minor class\", effort = Effort.MASSIVE, type = Type.PERFORMANCE)\npublic class MyClass {\n```\n\nYou can mark issues in statement blocks, unfortunately you can't use annotation in statement but **java-tech-debs** supply a method to mark some statement blocks using the *refComment* attribute.\nWith the *refComment* you can mark a comment as a technical debt comment that the system will use to identify the location of the block to mark, in the example the *refComment=\"AX\"* indicates a block that starts with a comment @TD-AX and ends with a line comment #TD-AX (AX is the code).\n\nImportant is: the start block is a multi-line java comment (not javadoc comment) with the first line that contains the block code @TD-{code}, all comment below this row will be used to set the *comment* attribute in the tecnical debt information.\nThe end of the block must be a single line comment starts with #TD-{code}\n\n```java\n @TechDebt(\n   comment = \"strange method2\", \n   author = \"CDA\", \n   severity = TechDebt.Severity.TRIVIAL, \n   type = Type.MAINTAINABILITY, \n   effort = Effort.MASSIVE,\n   refComment = \"AX\")\n public void execute2(Map\u003cString, Object\u003e params) {\n  @TechDebt(comment = \"bad variable\", author = \"me\", severity = TechDebt.Severity.MAJOR)\n  var a = 10;\n  var b = 20;\n\n  /*\n   * @TD-AX \n   * This is a test comment for AX\n   * \n   * to check\n   */\n  this.execute(null);\n  // #TD-AX\n  this.execute(null);\n\n }\n\n```\n\n### Step 4: Generate Reports\n\nOnce you have annotated the code, you can generate reports to monitor and manage technical debts. Run the Maven command to generate the report:\n\n mvn io.github.ihepda:tech-debt-maven-plugin:report\n\nor\n\n mvn site\n\nThis command will analyze the annotations in your code and generate a detailed report of the technical debts.\n\nOr, you can add the plugin in the *reporting* section of your *pom.xml*\n\n```xml\n \u003creporting\u003e\n  \u003cplugins\u003e\n   \u003cplugin\u003e\n          \u003cgroupId\u003eio.github.ihepda\u003c/groupId\u003e\n          \u003cartifactId\u003etech-debt-maven-plugin\u003c/artifactId\u003e\n       \u003cversion\u003e1.0.1\u003c/version\u003e\n    \n   \u003c/plugin\u003e\n  \u003c/plugins\u003e\n \u003c/reporting\u003e\n \u003cbuild\u003e\n  \u003cplugins\u003e\n   \u003cplugin\u003e\n    \u003cgroupId\u003eorg.apache.maven.plugins\u003c/groupId\u003e\n    \u003cartifactId\u003emaven-site-plugin\u003c/artifactId\u003e\n    \u003cversion\u003e3.12.1\u003c/version\u003e\n\n   \u003c/plugin\u003e\n  \u003c/plugins\u003e\n \u003c/build\u003e\n```\n\n#### Filtering\n\nissue: [Add report filter](https://github.com/ihepda/java-tech-debt/issues/6)\n\nThe report permits to set a filter in order to match only interested technical debts, for example technical debts sith a severity MAJOR or CRITICAL.\n\nThe filter is an 'SQL like filter', this is, you can use:\n\n* common operators : =, !=, \u003c=, \u003c, \u003e=, \u003e\n* like operator with or without the not keyword\n* in operator with or without the not keyword\n* and or conjunctions\n* grouping expression with '(' and ')'\n\nBelow an example\n\n```txt\ncomment like '%test%' and severity \u003e= 'MAJOR' or author in ('CDA', 'LA')\n\ncomment not like '%test%' and (severity = 'MAJOR' or author not in ('CDA', 'LA'))\n```\n\nIn order to activate the filter you have to add the *filter* configuration in the plugin\n\n```xml\n \u003creporting\u003e\n  \u003cplugins\u003e\n   \u003cplugin\u003e\n          \u003cgroupId\u003eio.github.ihepda\u003c/groupId\u003e\n          \u003cartifactId\u003etech-debt-maven-plugin\u003c/artifactId\u003e\n      \u003cversion\u003e1.0.1\u003c/version\u003e\n    \u003cconfiguration\u003e\n                       \u003cfilter\u003ecomment like '%test%'\u003c/filter\u003e\n    \u003c/configuration\u003e\n   \u003c/plugin\u003e\n  \u003c/plugins\u003e\n \u003c/reporting\u003e\n \u003cbuild\u003e\n  \u003cplugins\u003e\n   \u003cplugin\u003e\n    \u003cgroupId\u003eorg.apache.maven.plugins\u003c/groupId\u003e\n    \u003cartifactId\u003emaven-site-plugin\u003c/artifactId\u003e\n    \u003cversion\u003e3.12.1\u003c/version\u003e\n\n   \u003c/plugin\u003e\n  \u003c/plugins\u003e\n \u003c/build\u003e\n```\n\n#### Blocking the build\n\nissue: [Blocking the build if there are techdebts](https://github.com/ihepda/java-tech-debt/issues/11)\n\nThe maven plugin permits to block the build if same conditions are present. These conditions are defined\nusing a filter configuration. Below an example of filter configuration.\n\n```xml\n\u003cplugin\u003e\n  \u003cgroupId\u003eio.github.ihepda\u003c/groupId\u003e\n  \u003cartifactId\u003etech-debt-maven-plugin\u003c/artifactId\u003e\n  \u003cversion\u003e1.0.2-SNAPSHOT\u003c/version\u003e\n  \u003cexecutions\u003e\n    \u003cexecution\u003e\n      \u003cgoals\u003e\n        \u003cgoal\u003echeck\u003c/goal\u003e\n      \u003c/goals\u003e\n      \u003cconfiguration\u003e\n        \u003cfilter\u003eseverity.major \u003e 10\u003c/filter\u003e\n      \u003c/configuration\u003e\n    \u003c/execution\u003e\n  \u003c/executions\u003e\n\u003c/plugin\u003e\n```\n\nThe query language availabel is represented below:\n![alt text](images/maven-plugin-filterql.svg)\n\nAs identifier you can use:\n\n* ALL =\u003e Indicates all technical debts present in the project\n* SEVERITY.{severity value} =\u003e searches for all technical debts with a specific severity value\n* type.{type value} =\u003e searches for all technical debts with a specific type value\n\nIn the query language you are free to use _AND_, _OR_ and parenthesis, in order to compose complex conditions.\n\nFor example:\n\n```txt\nseverity.major \u003e 10 \n\nseverity.major \u003e 10 or type.security \u003e=1\n\nall \u003e 20 or (type.security \u003e 0 and severity.trivial \u003e0)\n```\n\n## Examples\n\nPlease see the example in **example** folder\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fihepda%2Fjava-tech-debt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fihepda%2Fjava-tech-debt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fihepda%2Fjava-tech-debt/lists"}