{"id":13941249,"url":"https://github.com/adr/adr-manager","last_synced_at":"2025-06-23T06:40:17.310Z","repository":{"id":37237205,"uuid":"304013826","full_name":"adr/adr-manager","owner":"adr","description":"ADR-Manager","archived":false,"fork":false,"pushed_at":"2024-07-11T05:18:04.000Z","size":7251,"stargazers_count":120,"open_issues_count":54,"forks_count":25,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-04-03T12:11:33.389Z","etag":null,"topics":["adr","architectural-decision-records","architecure","github","madr","madr-editor"],"latest_commit_sha":null,"homepage":"https://adr.github.io/adr-manager/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adr.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":"2020-10-14T12:51:16.000Z","updated_at":"2025-03-19T11:44:36.000Z","dependencies_parsed_at":"2024-11-18T21:44:18.268Z","dependency_job_id":"92e6dc83-8620-4a28-9d1e-e4b149373ee7","html_url":"https://github.com/adr/adr-manager","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/adr/adr-manager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adr%2Fadr-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adr%2Fadr-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adr%2Fadr-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adr%2Fadr-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adr","download_url":"https://codeload.github.com/adr/adr-manager/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adr%2Fadr-manager/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261430859,"owners_count":23157164,"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":["adr","architectural-decision-records","architecure","github","madr","madr-editor"],"created_at":"2024-08-08T02:01:14.858Z","updated_at":"2025-06-23T06:40:12.290Z","avatar_url":"https://github.com/adr.png","language":"JavaScript","readme":"# ADR-Manager ![General cypress report](https://github.com/adr/adr-manager/workflows/General%20cypress%20report/badge.svg?branch=cypress-integration) [![GitHub license](https://img.shields.io/github/license/adr/adr-manager)](https://github.com/adr/adr-manager/blob/main/LICENSE) [![GitHub last commit](https://img.shields.io/github/last-commit/adr/adr-manager)](https://github.com/adr/adr-manager/commits/main) [![GitHub issues](https://img.shields.io/github/issues/adr/adr-manager)](https://github.com/adr/adr-manager/issues) [![GitHub stars](https://img.shields.io/github/stars/adr/adr-manager)](https://github.com/adr/adr-manager/stargazers)\n\n\u003e A web-based application for the efficient creation and management of [architectural decision records (ADRs)](https://adr.github.io) in Markdown (MADR)\n\n## Description\n\n[MADR](https://adr.github.io/madr/) is a Markdown template for quickly capturing architectural decisions.\nIt offers a naming scheme and template to keep the layout of recorded decisions consistent.\nEach decision is stored in a separate file.\nThe ADR Manager currently only supports the management of MADRs stored in the folder `docs/adr` in GitHub repositories.\n\n## Quick Start\n\nYou can find the tool at https://adr.github.io/adr-manager.\n\n## Supported Browsers\n\nCurrently, the tool has been successfully tested in Chrome, Firefox, and Opera.\n\n### Usage\n\n1. After opening the tool, connect to GitHub. The tool needs your permission to access your GitHub repositories and email address.\n2. Add a GitHub repository. If your account does not have access to a repository with MADRs, you can simply fork one, e.g., \u003chttps://github.com/JabRef/jabref\u003e or \u003chttps://github.com/adr/adr-log\u003e.\n3. Now, you can edit any files in `docs/adr` of the GitHub repository.\n   Edit existing ADRs or create new ones.\n   One of the most important features is the MADR Editor that allows you to quickly draft a MADR while ensuring a consistent format.\n   ![This is the MADR editor in advanced mode.](docs/img/editor-screenshot.png)\n4. Do not forget to push your changes to GitHub, once you are done with editing the files.\n\nSome technical notes:\n\n- The `authID` (which enables the connection to GitHub) and changes to ADRs are stored in the local storage.\n  That way they are not lost when you reload the page or restart the browser.\n  However, changes will be lost when you either\n  - Clear local storage or\n  - Press the `Disconnect` button.\n- The general idea is that you directly push your changes to GitHub after editing.\n- During development, we may remove permissions for the OAuth App from time to time.\n  Do not be surprised, if you have to give permissions repeatedly.\n\n## Development\n\n### Prerequisites\n\n- Node.js and npm\n- A GitHub account with access to a repository with MADRs\n\n### Installation\n\nTo run the project locally, follow these steps:\n\n1. Clone this repository.\n2. Install dependencies with `npm install`.\n3. Compile and start the application with `npm start`.\n\nNote that, even when you run it locally, you need to connect to GitHub to use any functionality.\n\n### Using End-2-End Tests Locally\n\nWe use [Cypress](https://www.cypress.io/) for e2e testing.\nThe CI pipeline provides the necessary Oauth `authId` as an ENV variable.\nLocally, however, you'll need to provide one yourself.\nYou can either set `CYPRESS_OAUTH_E2E_AUTH_ID` and `CYPRESS_USER` containing the `authId` and `user` or create a `cypress.env.json` file and fill it with the following content:\n\n```json\n{\n  \"OAUTH_E2E_AUTH_ID\": \"*********\",\n  \"USER\": \"***********\"\n}\n```\n\nThe value of `OAUTH_E2E_AUTH_ID` and `USER` needs to be a valid `authId` and `user` from an active OAuth session, which you can obtain in the local storage (Chrome developer console -\u003e Application -\u003e Storage -\u003e Local Storage -\u003e `http://localhost:8080` -\u003e `authId`, `user`)\nThe involved GitHub account also needs to have developer access to the repo `adr/adr-test-repository-empty`.\nLastly, don't forget to start the app before running the e2e tests (`npm start`).\n\n### Useful Commands\n\nThe following commands are useful for development:\n\n```bash\n# install dependencies\nnpm install\n\n# build and start with hot-reload for development\nnpm start\n\n# build and minify for production\nnpm run build\n\n# run unit tests\nnpm test\n\n# run e2e tests\nnpm run e2e:test\n\n# open cypress GUI for e2e tests\nnpx cypress open\n\n# run a single e2e test\nnpx cypress run --spec ./cypress/e2e/adrManagerTest/\u003cfile-name\u003e\n\n# format code with prettier (do this before you commit and push)\nnpm run format\n```\n\n### Backend Setup\n\nThe project uses [OAuth] for the authentication to GitHub.\nIf you do not want to use this instance, you can easily set up your own by following these steps:\n\n1. Create an OAuth application on GitHub (see [here](https://docs.github.com/en/github-ae@latest/developers/apps/creating-an-oauth-app)).\n   - Copy the Client ID and Client Secret of the app (you'll need them later).\n2. Create a Github app on Firebase and in its configurations, set the Client ID and Client Secret as copied from the above Github app\n\n- Set the callback URL in Github Oauth app configuration to the one provided by Firebase.\n\n## Project Context\n\nThis project was started as an undergraduate research project at the Institute of Software Engineering of the University of Stuttgart, Germany.\nIt was also submitted to the [ICSE Score Contest 2021](https://conf.researchr.org/home/icse-2021/score-2021).\nSince then, it has been given over to the [ADR organization on GitHub](https://github.com/adr), where it is maintained and extended.\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadr%2Fadr-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadr%2Fadr-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadr%2Fadr-manager/lists"}