From ff8d30c142dd0c0ac44f731cb61b479f306b996a Mon Sep 17 00:00:00 2001 From: Bhavika Sehgal <133744950+Bhavika42@users.noreply.github.com> Date: Tue, 25 Mar 2025 13:27:11 +0530 Subject: [PATCH] Update GOVERNANCE.md --- GOVERNANCE.md | 456 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 452 insertions(+), 4 deletions(-) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 164b61cb..be29d49e 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -1,5 +1,453 @@ # Specification Governance +## Version +**0.6.0** + +## Draft Version +**Draft 03** + +## Previous Versions +- Draft 02 +- Draft 01 + +## Scope +This document intends to establish processes and guidelines that build a transparent, open mechanism for deciding how to manage contributions to the Beckn Protocol specification. The Core Working Group will initially follow these processes when merging changes from contributors. This guideline document will be adjusted as practicality dictates. + +This document is intended for the following audience: +1. Anyone who wants to understand how contributions are reviewed and merged by the Core Working Group. + +## Prerequisites +1. Readers must have a working knowledge of Git. +2. Readers should also know how open-source repositories are managed on GitHub. +3. Readers must have knowledge and understanding of the Beckn Protocol specification. + +## Context +The Beckn Protocol exists as a set of specifications documented within public repositories on GitHub at [https://github.com/beckn](https://github.com/beckn). These repositories contain specification documents, reference implementations, tools, and utilities. Like all version-controlled open-source repositories, there are processes that must be adopted to manage changes to the files present in these repositories. + +The most common way a change is proposed to the specification is via an issue linked to that repository, which ultimately gets converted to a pull request linked to that issue. These pull requests must then be reviewed by the maintainers of the repository and subsequently merged with the main/master branch of that repository. + +# Abstract + +The Beckn Protocol specification evolves based on real-world use cases. While the Core Working Group may explore hypothetical scenarios, all specifications should be grounded in practical applications.Managing contributions follows structured policies and processes that evolve alongside the protocol.Given Beckn's global scope, maintainers must ensure that any committed changes have a clear, worldwide impact. This document outlines the governance model, design principles, and review process for incorporating contributions into the specification. + +# Terminology + +1. **Git:** A decentralized version control system. +2. **GitHub:** A platform for managing shared repositories using Git. +3. **Pull Request:** A request to merge proposed changes into the repository. +4. **Core Working Group:** The team responsible for maintaining the specification. + +# Expected Outcomes + +After reading this document, the reader should be able to: + +- Understand the contribution review and approval process. +- Follow governance principles for managing specification changes. + +# The Beckn Credo + +The Beckn community is fully open—no registrations, memberships, or partnerships required.Beckn Protocol offers a lightweight yet accessible framework for universal adoption.Businesses and organizations worldwide leverage Beckn for digital acceleration, fostering a level playing field for all market participants, big or small. + +# Motivation + +Beckn aims to make the internet more small-business friendly, acting as a force multiplier with minimal footprint. + +# Guiding Lights + +- Open specifications with equal access. +- Retaining agency for small businesses. +- Supporting non-rivalrous, non-exclusive networks. + +# Community Driven + +- Enhance value for all participants. +- Empower individuals to weave networks in their own way. +- Encourage contributions to specifications and best practices. + +Beckn Protocol is an open framework with a modular core, enabling market players to build seamless digital experiences and networks. Similar to how HTTP revolutionized digital communication, Beckn fosters interoperability and accessibility in the digital economy. + +# Open Community Contributions + +Beckn Protocol has welcomed community contributions to its specification since May 2020. + +# Design Principles for Specification Evolution + +To ensure high-quality contributions from the Beckn community, the following principles guide the review and approval process: + +## Interoperability +New features must enhance interoperability across implementations. + +## Abstraction +Features should be abstracted to support diverse global use cases, avoiding ties to specific domains, regions, or industries. + +## Optimal Ignorance +Before inclusion, reviewers must ask: +- _Do we need it?_ +- _Do we need it now?_ +Only if both answers are "Yes" should the feature be added. + +## Security +All new features must undergo security assessments. Free-text and loosely-typed fields should be minimized. + +## Privacy and Consent +Personally identifiable information (e.g., age, gender, contact details) should not be collected unless governed by explicit consent mechanisms. + +## Scalability +Features must be scalable and adaptable, considering the varied capabilities of implementers. + +## Reusability +New features should prioritize reusing existing schema components whenever possible. + +# Unification over Standardization + +Not all features can be globally standardized, as values may vary by domain, region, and adoption. If multiple standards exist for a single feature, both should be supported rather than enforcing a new standard. For example, if a location schema includes both GPS coordinates and addresses, the feature should support both rather than choosing one. + +Exceptions to this approach will arise, and the Core Working Group is responsible for handling these cases logically and documenting deviations clearly. + +# Introduction + +Beckn Protocol follows an open, community-driven governance model. Businesses and organizations collaborate across domains, technologies, and expertise to shape the specification. A standardized process is essential for evolving the specification and providing historical context for changes. Beckn's governance model incorporates best practices from globally recognized governance frameworks. + +The evolution of Beckn Protocol is managed by the **Core Working Group**, consisting of members from the **Beckn Open Community** with expertise in architecture, open-source development, and industry practices. This group reviews proposals, manages releases, engages with community members, and expands its team as needed. + +The Core Working Group holds weekly meetings to review open pull requests and discuss issues related to the evolving specification. These meetings are open to the community. + +This governance model is inspired by the [OpenAPI](https://www.openapis.org/participate/how-to-contribute/governance) and IETF governance models. + +## Need for Governance + +Since the core specification is abstract, implementers must adapt it for different domains, regions, and scopes. Policies applied to the core specification define its implementation. A strong, inclusive governance model is required to balance adherence to fundamental design principles with an adaptive, community-driven approach to evolution. + +## Areas That Require Governance + +The Beckn Protocol consists of multiple independently governable areas, each managed by dedicated working groups. The following key areas have been identified: + +## Design Principles + +Beckn Protocol specification adheres to core design principles that guide its evolution. These principles are not static and must evolve over time to ensure long-term relevance. The Core Working Group must: + +- Document design principles clearly and unambiguously. +- Identify and eliminate overlaps between principles to ensure atomic definitions. +- Define a structured methodology for applying principles to specification changes. +- Provide sufficient examples for contributors to self-assess proposals before submission. +- Regularly evaluate principles against real-world scenarios to ensure continued applicability. +- Track and document any deviations from principles, recommending corrective actions. + +## Licensing + +Beckn Protocol is currently licensed under Creative Commons. However, licensing may evolve based on community adoption. The Core Working Group must: + +- Clearly define permissible and restricted use cases under current licensing. +- Gather feedback from implementers on licensing challenges. +- Offer solutions to address licensing concerns. +- If necessary, explore licensing modifications to enhance flexibility while preserving interoperability. + +## API + +Beckn Protocol defines a set of actions that may be implemented as APIs. The Core Working Group must: + +- Define supported API methods and their intended use cases. +- Document APIs using machine-readable formats such as OpenAPI and AsyncAPI. +- Establish testing methodologies to validate API implementations. +- Continuously extend API capabilities to support evolving use cases. + +## Schema + +Beckn Protocol defines a standardized schema for runtime object instantiation. The Core Working Group must: + +- Define schemas with clarity and precision. +- Document schemas using standard formats such as JSON Schema. +- Develop methodologies to validate schema integrity across use cases. +- Expand schema support through extensions and additions. +- Enable mapping of sector-specific models to the core schema. + +## Communication + +Beckn Protocol specifies a standardized communication protocol for API interactions. The Core Working Group must: + +- Define exchange mechanisms through UML sequence diagrams. +- Link schema and API definitions within interaction sequences. +- Provide clear, concise explanations of interactions. +- Map real-world consumer-provider interactions to Beckn Protocol workflows. + +## Architecture + +Beckn Protocol specifies a standard reference architecture of an open network. The key network actors include BAP, BPP, BG, and a Network Registry. The Core Working Group must: + +- Document the ecosystem architecture clearly and unambiguously using machine-readable formats, including UML diagrams where applicable. +- Define each architectural layer and the actors involved. +- Clearly specify the roles and responsibilities of each network actor. +- Maintain an up-to-date, technology-agnostic, high-level reference implementation architecture document for each network actor. +- Establish processes for adding new network actors to the specification. +- Periodically evolve the architecture based on community contributions. + +## Area Director (AD) + +Each governance area will have an **Area Director (AD)** responsible for overseeing the formation and functioning of Working Groups (WG). The AD appoints WG Chairs and ensures adherence to the core design principles while reviewing proposals submitted by contributors. The AD is a volunteer from the Beckn community and plays a critical role in governance. + +## Working Groups (WG) + +A Working Group consists of contributors responsible for managing the evolution of specific areas within the specification. + +### Purpose of Specification Working Groups + +Working Groups drive the refinement and evolution of Beckn Protocol through collaborative efforts, ensuring alignment with real-world needs. + +### Working Group Roles + +Each WG includes the following key roles: + +1. **Administrator** +2. **Core Committer** +3. **API Designer** +4. **System Architect** +5. **Community Manager** +6. **Project Manager** +7. **Subject Matter Expert** +8. **Implementation Expert** +9. **Call Moderator** +10. **Scribe** + +### Administrator + +Each WG will have an **Administrator (Admin)** responsible for declaring rough consensus on key decisions. While full consensus is preferred, rough consensus ensures progress when disagreements arise. The Admin has authority over WG assets such as repositories, documentation, and communication channels. + +More than one person may qualify for the Admin role, but only one serves in this capacity at a time. Additional members are selected through a mutually agreed process within the WG. + +# **Selection Criteria for a WG Admin** + +A WG (Working Group) Admin must meet the following criteria: + +1. **Architectural Expertise** – Strong knowledge of software architecture and system design. +2. **Domain Expertise** – Experience across multiple industry sectors. +3. **Implementation Expertise** – Hands-on experience with multiple technologies. +4. **Beckn Protocol Knowledge** – In-depth understanding of Beckn protocol design principles and applications. +5. **Open-Source Experience** – Proven contributions to open-source projects. +6. **Git and GitHub Management** – Proficiency in using Git and GitHub for version control and collaboration. + +--- + +## **Core Committers** + +Each WG must have at least one **Core Committer** responsible for: + +- Reviewing proposals. +- Evaluating protocol drafts. +- Participating in discussion threads. +- Reviewing and merging pull requests (PRs) to the specification. + +### **Selection Criteria for a Core Committer** + +1. **Architectural Expertise** – Comprehensive understanding of software architecture. +2. **Domain Expertise** – Broad experience across multiple industries. +3. **Implementation Expertise** – Hands-on knowledge of various technologies. +4. **Beckn Protocol Knowledge** – Deep understanding of Beckn protocol and its applications. +5. **Open-Source Experience** – Active engagement in open-source projects. + +--- + +## **Working Group Members** + +- Anyone can request to join a WG by sending an email to the WG Admin. +- WG members can participate in discussions, respond to comments, and attend meetings. +- However, WG members do not have decision-making authority over merging PRs into the specification. + +--- + +# **Managing Specification Evolution** + +The specification will evolve based on the following criteria: + +1. **Clarity** – The current approach is unclear or overly complex. +2. **Consistency** – The specification should align with industry standards and internal consistency. +3. **Necessary Functionality** – Missing functionality that limits practical implementation. +4. **Forward-Looking Designs** – Anticipating future trends, protocols, and API evolutions. +5. **Impact** – Changes should support common and critical use cases without being driven by rare edge cases. + +--- + +## **Specification Evolution Guidelines** + +All changes must undergo a rigorous review process. Core committers must evaluate proposals based on: + +1. **Relevance** – Does the change align with Beckn protocol's scope? +2. **Migration Impact** – How easy is the transition from the existing specification? +3. **Tooling** – Does the change support various code generation and interface utilities? +4. **Visualization** – Can the change be represented graphically? + +### **Approval Process:** + +- Specification changes require approval from a majority of core committers. +- Approval should be documented via GitHub comments (e.g., "Approved by @cwgadmin"). +- At least one formal GitHub-based approval must be recorded before merging. +- No changes should be merged without accompanying documentation. + +--- + +# **Feature Evolution** + +New features follow a structured lifecycle: + +1. **Proposed** – Initial submission for consideration. +2. **Draft** – Under discussion and refinement. +3. **Recommended** – Recognized as valuable but not mandatory. +4. **Required** – Fully integrated into the core specification. + +### **Process for Feature Evolution:** + +- All proposals should follow the namespace structure outlined in `CONTRIBUTIONS.md`. +- WG members must review, classify, and rename proposals accordingly. +- Future specification development will occur in a **draft branch** before merging into the master branch upon release. + +--- +# Proposal Guidelines + +## Proposal Namespace Structure + +All proposals will follow the namespace structure: + +``` +./@alice-dev.direction.proposed +``` + +## Draft Features Namespace Structure + +All draft features will use the following namespace: + +``` +./@proposer.feature.draft +``` + +## Recommended Standard Namespace Structure + +All recommended standards will use the namespace: + +``` +./@proposer.feature.recommended +``` + +## Required Standard Namespace Structure + +All required standards will follow the namespace below on the draft branch. Before merging to the master branch, these namespaces must be replaced with feature names: + +``` +./@proposer.feature.required +``` + +### Not Recommended Namespace + +``` +./@proposer.direction.not-recommended +``` + +# Working Group Weekly Meetings + +To review change requests to the specification, Working Groups should discuss and decide on their inclusion in weekly meetings. The agenda consists of the following: + +1. **Bugs:** + - Discuss all issues raised as bugs. + - Highest priority. + - Must be acknowledged and resolved within one week of submission. + +2. **Proposed Enhancements:** + - Review all new feature proposals submitted as Pull Requests (PRs) to draft branches. + - Prioritization of proposals: + 1. Minor Version Draft Branch + 2. Patch Version Draft Branch + 3. Major Version Draft Branch + - PRs to the master branch must be explicitly rejected. + +3. **Draft Features:** + - Review previously accepted proposals classified as draft features. + - Decide whether to classify them as **Recommended** or **Not Recommended** standards. + +4. **Recommended Standard:** + - Review all draft features classified as **Recommended Standards**. + - Decide whether a **Recommended Standard** should be elevated to a **Required Standard**. + +5. **Final Decision and Commit Approvals:** + - List commits to be merged into various branches. + +The Working Group Administrator (WG Admin) sets the meeting duration. If proposals are not reviewed within the meeting, the WG Admin may propose a second meeting. + +# Change Tracking and Management + +**GitHub** serves as the medium of record for specifications, designs, and use cases. + +All specification documents are available in the official Beckn Protocol GitHub account [here](https://github.com/beckn). + +## Sources of Truth + +1. **protocol-specifications:** Core transaction API specification. +2. **registry:** Implements registry infrastructure. +3. **specification-files:** Contains all human-readable specification documents. + +## Branch Structure + +At any time, there can be a maximum of **four** working branches: + +- **master:** Stable version (No direct PRs modifying specifications; only supporting files allowed). +- **core-0.9.3-draft:** Next **PATCH** version (non-breaking changes like typo and document fixes). +- **core-0.10.0-draft:** Next **MINOR** version (backward-compatible changes like attribute additions). +- **core-1.0.0-draft:** Next **MAJOR** version. + +The master branch will always reflect the current released Beckn Protocol specification. + +### Workflow Labels + +Labels indicate the workflow stage of a specification change: + +- **proposed** +- **draft-*** +- **recommended** +- **required** +- **not-recommended** +- **review** (candidate for upcoming WG meeting) +- **rejected** +- **needs-approval** + +Labels should be lowercase with dashes instead of spaces. WG members assign these labels. + +Each feature change must have an associated issue. A PR should link to the issue and describe the proposed solution. Examples of the current vs. proposed implementation should be included. + +# Reviewing Pull Requests + +- Any PR must have an associated issue. +- If an issue is not present, the reviewer must comment, requesting the contributor to raise an issue and link the PR to it. +- If the issue is not raised within 24 hours, the PR is **rejected** with the comment: _“Closing this due to unlinked Issue.”_ + +## Managing Conflicts + +- If a PR has merge conflicts, the reviewer will comment: _“Merge conflicts present, kindly resolve and re-submit PR.”_ +- If conflicts are not resolved within 24 hours, the PR is **rejected** with the comment: _“Closing this due to unresolved merge conflicts.”_ + +# Release Process + +A release requires a **vote** by CWG members within the voting period. + +### Voting Periods + +- **Patch releases:** Majority approval required (Max: 3 days) +- **Minor releases:** 66% approval required (Max: 7 days) +- **Major releases:** 66% approval required (Max: 14 days) + +The CWG Admin may override voting requirements based on team size and project needs. Patch releases occur in the first CWG meeting of each month. + +# Transparency + +- The process should be transparent. +- Discussions involving sensitive customer data must be anonymized or conducted offline. +- General discussions should take place on GitHub issues. + +# Participation + +- The CWG governs the specification. +- Evolution happens through participation from the developer community. +- Contributions can include filing or discussing issues, creating PRs, and assisting others. + + +