Decision log of Identity

[JennyPng]

Azure/azure-sdk-tools#16050

asked Copilot to analyze git history, PR descriptions, etc. to document a historical timeline of (non-obvious) decisions made when developing Identity

experiment to see if this is useful context to have in the repo for agents. would possibly require automated agentic workflows to maintain

Prompt:

Build a decision.md file for azure-identity SDK, documenting a historical, chronological list of key architecture/design decision with relevant PR citations. Similar to a changelog, but for deeper context on why things are the way they are now. Look at major commits in git history , git blame, cross reference key PR descriptions or comment threads on those PRs for context on WHY we made any decisions. Focus not on obvious information already covered in main docs, but rather any non-obvious context to help new developers or agents understand how to work in the codebase.

[pvaneck]

Overall, looks pretty good. Left some comments.

[richardpark-msft]

It could be useful to have copilot make a pass at categorizing these a bit and maybe adding a ToC for that (this would avoid reordering the entire document, which I assume you want to be chronological)

[Copilot]

Pull request overview

This PR adds a new design-decisions.md "Architecture Decision Log" to the azure-identity package — a chronological, non-obvious record of key design/architecture decisions with citations to the PRs (and review discussions) that introduced them. It is positioned as an experiment to give new developers and agents deeper "why" context that isn't covered by the existing user-facing docs. The README is updated to link to it, and cspell.json gets two new allowed words for the new file. The change is documentation-only and introduces no code or behavioral changes.

I spot-checked a representative sample of the historical claims against the current source (e.g., service_fabric.py's connection_verify=False pylint disable, AZURE_IDENTITY_DISABLE_MULTITENANTAUTH, FailedDACCredential, the resolve_tenant "organizations" carve-out, and the AZURE_TOKEN_CREDENTIALS/Kubernetes env vars) and found them accurate. The README link target, TOC anchors, and cspell additions are all correct.

Changes:

• Add sdk/identity/azure-identity/design-decisions.md (551 lines) documenting design decisions by year with PR citations and maintenance guidance.
• Add a link to the decision log from the README's Contributing section.
• Add nocae and ROPC to cspell.json for the new file.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
sdk/identity/azure-identity/design-decisions.md	New architecture decision log; content verified against codebase on a sample basis; two entries deviate from the doc's own year-month date convention.
sdk/identity/azure-identity/README.md	Adds a link to the new decision log, consistent with the existing absolute-URL link style.
.vscode/cspell.json	Adds nocae and ROPC as allowed words for the new file (other identity jargon is already tolerated).