docs(adr): create decision record guide and template

[g-husam]

View the rendered readme guide here: https://github.com/googleapis/librarian/blob/docs/adr-template/doc/decision-records/README.md

[gemini-code-assist]

Code Review

This pull request introduces a new README file for decision records, detailing when and how to write them. The review feedback focuses on aligning the Markdown formatting with the Google Markdown Style Guide, specifically by wrapping lines to adhere to the 80-character limit, removing trailing whitespace, and using an explicit path for the internal template link.

[codyoss]

Should we tell gemini about these files/dir and when to write/update one in GEMINI.md?

[g-husam]

yeah we can tell it about it in GEMINI.md, to reference when appropriate, I'll add (tho historically Gemini is pretty poor at following those instructions IME lol). Maybe not to write one, as I'd leave it to the human to decide that since its usually the human knowing when to write one and driving that decision.

[g-husam]

actually I'm not sure when this context is really needed, as its more historical reference, so might be better to just leave it out and let developers add to context when deemed necessary, to avoid polluting it?

[hj690]

💯

[noahdietz]

I kind of wish we just had Current and Superseded - I feel like we shouldn't submit the PR in Proposed state bc its not clear if its authoritative or not ("well it was checked in, but its not approved so...?"), and when we'd update it to Accepted or remove it altogether.

Basically I feel like any PR introducing a new one is effectively the Proposed state, and if it is checked in it is at first Current, until it is deprecated/superseded, at which point it is Superseded.

Thoughts?

[g-husam]

yeah good point, it should be in one of the (semi) terminal states, like accepted, rejected (still very valuable!!), superseded, etc.

[g-husam]

although I guess proposed captures when it was first created/started discussion