docs(decisions): add architectural decision records structure

[gustavovalverde]

Motivation

Sometimes we make architectural decisions that can have a great impact even though their implementation seems easy or trivial, and these decisions—if we decide to change them—should be documented to avoid pitfalls that were previously considered by their authors, but are hidden in conversations across different platforms, or in discussions in PRs.

Thus we required a place to leave those decisions defined, and easily track their changes, and using git for this purpose is the best as it provides:

• Version control and history tracking of decision evolution
• Clear attribution of changes and contributions
• The ability to reference specific decisions in issues and PRs
• Integration with our existing development workflow
• Discoverability through the same tools we use daily

This approach introduces a structured system for documenting important architectural decisions across multiple domains of the Zebra (DevOps, Network, Consensus, etc.), creating transparency around our technical choices and their rationale.

Solution

• Add a decision records directory structure with domain-specific subfolders
• Include a README explaining the purpose and usage of decision records
• Provide a standardized template for creating new decision records
• Add an initial DevOps decision record for filesystem hierarchy standardization
• Structure follows a modified MADR (Markdown Architectural Decision Records) approach

Tests

• Validated markdown formatting and structure
• Ensured links in the README function correctly
• Verified the template can be used to create new decision records

Specifications & References

• ADR GitHub Organization
• Michael Nygard's original ADR article
• MADR Templates

Follow-up Work

• Document existing architectural decisions that haven't been captured yet
• Consider adding a decision record index or navigation system as the number of records grows
• Integrate decision record references into relevant parts of the codebase documentation

PR Checklist

• The PR name is suitable for the release notes.
• The solution is tested.
• The documentation is up to date.
• The PR has a priority label.
• If the PR shouldn't be in the release notes, it has the C-exclude-from-changelog label.