RFC3: Architecture Decision Records

  • date: 2024-02-17
  • author: Francesco Bartoli
  • contact: xbartolone@gmail.com
  • status: draft
  • modified: 2024-02-17

Summary

Adoption of Architectural Decision Record (ADR) methodology as best practice

Background

As the pygeoapi project evolves and scales, it becomes increasingly important to establish clear documentation and communication channels regarding architectural decisions. Currently, the pygeoapi project lacks a standardized method for documenting architectural decisions. This lowers the ability of contributors, maintainers, and stakeholders to understand the reasoning behind certain design choices and may lead to misunderstandings or inefficiencies during the development process. At the moment architectural decisions are fragmented and hidden in the discussions of the issues/PRs themself.

This RFC proposes the adoption of Architectural Decision Records (ADRs) as a best practice within the pygeoapi project. It serves as a starting point for discussing the feasibility and implications of adopting ADRs within the pygeoapi project.

Feedback and contributions from the community are welcomed and encouraged to help shape the proposed implementation plan and ensure its successful adoption.

Architectural Decision Records (ADRs)

One approach gaining traction in the software development community is the use of Architectural Decision Records (ADRs). ADRs provide a structured way to capture important architectural decisions, their contexts, and the rationale behind them, thereby promoting transparency and aiding in future decision-making processes. They will be available as a markdown files under the documentation folder and eventually made published and searchable as web pages.

An ADR may or may not be linked to a pull request but when there is a particular focus/impact on the design of the pygeoapi architecture then it can be required (if missing) as part of the review process to converge toward an architectural change with a documented and clear consensus/rejection.

By adopting ADRs as a best practice, the pygeoapi project can enhance its architectural governance processes, foster collaboration among contributors, and ultimately deliver more robust and maintainable software solutions.

By formally documenting key architectural decisions, we aim to achieve the following benefits:

  • Transparency: ADRs provide transparency into the thought process behind architectural decisions, allowing contributors and stakeholders tounderstand the rationale and implications of various design choices.
  • Consistency: A standardized format for documenting architectural decisions promotes consistency across the project, making it easier for new contributors to understand the project's architecture and guiding future decision-making processes.
  • Knowledge Sharing: ADRs serve as a valuable knowledge-sharing tool, capturing the collective wisdom and experience of the project's contributors and enabling knowledge transfer across team members.
  • Risk Mitigation: Documenting architectural decisions helps mitigate the risk of future misunderstandings or disputes by providing a clear record of the rationale behind each decision.

Implementation Plan

To adopt ADRs as a best practice within the pygeoapi project, the following steps are proposed.

Education and Awareness

Raise awareness among contributors, maintainers, and stakeholders about the benefits of ADRs and the proposed adoption process.

Establishment of Guidelines

Define clear guidelines for creating, maintaining, and organizing ADRs within the project repository.

Integration with Development Workflow

Integrate the creation and review of ADRs into the project's development workflow to ensure that important architectural decisions are documented in a timely manner.

Documentation

Update the project's documentation to include information on ADRs, their purpose, and how they should be used within the context of the pygeoapi project.

Community Engagement

Encourage community participation in the creation and review of ADRs to ensure that a diverse range of perspectives is considered in the decision-making process.

Voting History

To be started.