{"id":14156423,"url":"https://github.com/adr/e-adr","last_synced_at":"2025-05-13T19:33:19.152Z","repository":{"id":47401044,"uuid":"55391726","full_name":"adr/e-adr","owner":"adr","description":"Architectural Decisions Records embedded in Java code","archived":false,"fork":false,"pushed_at":"2025-05-12T06:51:38.000Z","size":1191,"stargazers_count":33,"open_issues_count":6,"forks_count":7,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-05-12T07:41:58.221Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://adr.github.io/e-adr/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"epl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adr.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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,"zenodo":null}},"created_at":"2016-04-04T07:08:55.000Z","updated_at":"2025-05-12T06:51:40.000Z","dependencies_parsed_at":"2024-01-13T02:50:38.203Z","dependency_job_id":"c39f519a-114c-435d-b136-45bed3c3c719","html_url":"https://github.com/adr/e-adr","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adr%2Fe-adr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adr%2Fe-adr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adr%2Fe-adr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adr%2Fe-adr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adr","download_url":"https://codeload.github.com/adr/e-adr/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254013144,"owners_count":21999365,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-08-17T08:05:27.826Z","updated_at":"2025-05-13T19:33:18.818Z","avatar_url":"https://github.com/adr.png","language":"Java","funding_links":[],"categories":["Decision Records (ADR/RFC)","others"],"sub_categories":["Design Patterns"],"readme":"# Embedded Architectural Decision Records\n\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.github.adr/e-adr/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.github.adr/e-adr)\n[![Javadocs](https://javadoc.io/badge/io.github.adr/e-adr.svg)](https://javadoc.io/doc/io.github.adr/e-adr)\n[![License](https://img.shields.io/badge/license-EPL-blue.svg)](LICENSE)\n\n\u003e Architectural knowledge captured in architectural designs and [architectural decisions](https://en.wikipedia.org/wiki/Architectural_decision) is primarily created and consumed in tools made for software architects.\n\u003e Developers, also consuming and creating architectural knowledge, do not always use such tools;\n\u003e this adds to the gap between these two roles often observed in practice.\n\u003e Architectural erosion and knowledge vaporization are two of the consequences.\n\nWith this repository, we show how to narrow the gap with architecture domain-specific Java annotations.\nThese annotations allow developers to reference and create architectural decision knowledge directly in code.\nThis knowledge can then automatically be processed by other tools to provide additional integration and collaboration capabilities.\n\nCurrently, following architectural decision records are supported:\n\n- [Markdown Architectural Decision Records](https://github.com/adr/madr) (\"MADR\") - lean architecture decision records using markdown\n- Y-Statements - [Sustainable Architectural Decision Records](https://www.infoq.com/articles/sustainable-architectural-design-decisions)\n\nSee \u003chttps://adr.github.io\u003e for more information on architectural decision records.\n\n## Examples\n\n### Example for complete embedding\n\n```java\n@MADR(value = 1,\n    title = \"Implement entire business logic layer as POJO\",\n    contextAndProblem = \"Need to select a single consistent ComponentImplementationParadigm' for entire business logic layer\",\n    alternatives = {\"POJO\", \"JEE EJB\", \"Spring Bean\"},\n    chosenAlternative = \"POJO\",\n    justification = \"Because it is a company-wide policy, see http://www.iaas.uni-stuttgart.de/institut/ehemalige/zimmermann/indexE.php\",\n    relatedDecisions = {2, 3})\npublic class MADRAnnotationDemoClass {\n    public int sampleBusinessLogic(String input) {\n        return 42;\n    }\n}\n```\n\n`@MADR` indicates that the annotation used the format defined by the \"Markdown Architectural Decision Record\".\nThe content is directly embedded in the annotation.\n\n### Example for a linked ADR\n\n```java\n@ADR(1)\npublic class MADRAnnotationDemoClass {\n    public int sampleBusinessLogic(String input) {\n        return 42;\n    }\n}\n```\n\nBy using `@ADR(1)`, the annotation points to `ADR 0001`.\nThe convetion is that the decisions are stored in `docs/adr/` with a running number.\nThey can be of an arbirary format, such as MADR or [Michael Nygard's format](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions), which is supported by [adr-tools](https://github.com/npryce/adr-tools).\nExample MADRs can be seen at the [ADR log of the adr-log tool](https://github.com/adr/adr-log/blob/master/docs/adr/index.md).\n\n## Use in your projects\n\n[Search maven central](https://search.maven.org/search?q=a:e-adr) for the latest version.\n\nGradle:\n\n```groovy\nimplementation 'io.github.adr:e-adr:{version}'\n```\n\nMaven:\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003eio.github.adr\u003c/groupId\u003e\n  \u003cartifactId\u003ee-adr\u003c/artifactId\u003e\n  \u003cversion\u003e{version}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Development information\n\nTo upload to maven central, the gradle task `publsihToSonatype` at `io.github.adr.embedded` is used.\nThereby the [Gradle Nexus Publish Plugin](https://github.com/gradle-nexus/publish-plugin/) plugin is used.\n\n## Related work\n\n- [Documenting Implementation Decisions with Code Annotations](https://www.researchgate.net/publication/280014035_Documenting_Implementation_Decisions_with_Code_Annotations)\n  - Uses JavaDoc\n  - Requires external tool to allow for auto completion\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadr%2Fe-adr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadr%2Fe-adr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadr%2Fe-adr/lists"}