diff --git a/GOVERNANCE.md b/GOVERNANCE.md index c42a95a8..2036bf80 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -1,27 +1,27 @@ # Specification Governance -## Draft 02 +## Version 0.5.0, Draft 01 # Authors 1. Ravi Prakash : ravi@becknfoundation.org -# Latest Version +# Draft Version -Draft 02 +Draft 03 # Previous Versions -Draft 01 | Deprecated +- Draft 02 +- Draft 01 # Scope -This document intends to establish processes and guidelines which 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 external contributors or from the CWG itself. This guideline document will be adjusted as practicality dictates. +This document intends to establish processes and guidelines which 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 @@ -30,8 +30,7 @@ This document is intended for the following audience. # Context -Beckn protocol exists as a set of public repositories on Github at 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. - +Beckn protocol exists as a set of specifications documented within public repositories on Github at 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 @@ -43,65 +42,53 @@ The evolution of beckn protocol specification is always use-case driven. The Cor 1. **Git:** A decentralized version control software 2. **Github:** An online platform for managing shared repositories via git 3. **Pull Request:** A request to merge a change to an existing version of the repository -4. **Core Working Group:** Current maintainer and governing authority of the specification +4. **Core Working Group:** Current maintainer of the specification # Expected Outcomes after reading this document After reading this document, the reader should be able to -1. Understand how to review and merge changes to the specification - -# Introduction - -The Beckn protocol is maintained via an open community-driven governance model. The community comprises multiple businesses and organizations that actively contribute to the specification to fuel their digital acceleration. This collaboration across domains, technologies and expertises will bring in new ideas which need to be part of the protocol. Hence there is a need for a standardised process for making relevant changes to the specification as well and for a retrospective understanding of the specification. The governance model for beckn protocol has been created using some of the best practices of globally recognized governance models. - -Evolution of beckn protocol specification is guided by the **Core Working Group**. This working group contains members that bring their API expertise, industry knowledge, incorporate feedback from the community, and expand the group of committers as and when appropriate. All development activity on the future specification will be performed as features on a draft branch and merged into this branch. Upon release of the future specification, this branch will be merged to master. - -The Core Working Group holds weekly web conferences to review open pull requests and discuss open issues related to the evolving specification. Participation in weekly calls and scheduled working sessions is open to the community. - -This governance model is inspired from the [OpenAPI specification governance model](https://www.openapis.org/participate/how-to-contribute/governance). - +- TODO +- TODO # The Beckn Credo - -The Beckn community is an open community. So, no registrations. No memberships. No partnerships. Just a minimal footprint of an open and equally accessible Beckn Protocol that anyone can use. Multiple businesses and organizations have started using beckn protocol to fuel their digital acceleration. The credo of being an open protocol creates a level-playing field for any market player, small or large. - +The beckn community is an open community. So, no registrations. No memberships. No partnerships. Just a minimal footprint of an open and equally accessible Beckn Protocol that anyone can use. Multiple businesses and organizations have started using beckn protocol to fuel their digital acceleration. The credo of being an open protocol creates a level-playing field for any market player, small or large. ## Motivation - To make the internet small-business friendly. be a force multiplier with minimal footprint. ## Guiding Lights - Open specs, equal access. retain agency of small businesses. non-rivalrous, non-exclusive networks ## Community Driven - Increase value for all participants. be a network weaver in your own way. be a contributor of specs and best practices -The Beckn Protocol is an open commerce protocol with an abstract core, which is enabling market players to reimagine building seamless digital experiences and networks. This is very similar to how HTTP, while being a simple and open protocol has fueled seamless interaction between multiple systems and led to an explosive growth in internet adoption. +Beckn protocol is an open protocol with an abstract core, that is enabling market players to re-imagine building seamless digital experiences and networks. This is very similar to how HTTP, while being a simple and open protocol has fueled seamless interaction between multiple systems and led to an explosive growth in internet adoption. ## Open Community Contributions +Beckn protocol has been accepting community contributions to the specification since May 2020. -The Beckn Protocol has been accepting community contributions to the specification since May 2020. - -# Design Principles +# Design Principles for Specification Evolution +To allow contributions from the beckn open community, the following design principles need to be applied while reviewing or proposing changes to the specification. They are: -To allow open contributions from the community, a governance model is required to apply some basic design principles while reviewing or proposing changes to the specification. They are: +## Interoperability: +Any feature added to the specification must ensure that it increases interoperability between implementations. -## Interoperability via Abstraction: +## Abstraction Any feature included in the specification must be abstracted so as to allow it to be consumed across a global range of use cases. That means no feature should be linked to a specific domain, region or use case. ## Optimal ignorance: -Before including any feature in the specification, reviewers should ask the following questions: a) _Do we need it?_ And, b) _Do we need it now? If the answer to both these questions is “Yes” then this criteria will have been met. +Before including any feature in the specification, reviewers should ask the following questions: a) _Do we need it?_ And, b) _Do we need it now?_ If the answer to both these questions is “Yes” then that feature may be included in the specification. -## Privacy and Security -Any feature being included in the specification must be tested for any security or privacy vulnerabilities. Free text fields, loosely-typed fields and any fields that may be used to implicitly capture Personally Identifiable Information should not be accepted. +## Security +Any feature being included in the specification must be tested for any security vulnerabilities. Free text fields, loosely-typed fields should be avoided. -## Scalability +## Privacy and Consent +Any feature that may be used to explicitly capture Personally Identifiable Information should not be accepted. Features especially like age, gender, contact information must be avoided and must only be shared via a consent mechanism. -Any feature being included in the specification must be tested for scalability. String fields with unlimited size; arrays with unlimited size etc, must be discouraged. Any feature that is included must work at scale. +## Scalability +Any feature being included in the specification must be tested for scalability. Any feature that is included must be agnostic of scale. Contributors should keep in mind that the implementors may not always have the capability to scale their platform and hence contributors should be aware of this limitation while proposing changes to the spec. ## Reusability Any new feature must be checked if it can reuse components from the existing schema before inclusion into the specification. @@ -109,26 +96,69 @@ Any new feature must be checked if it can reuse components from the existing sch ## Unification over Standardization Not all features across the globe can be standardized. Standard values vary with domain, region and adoption. In case multiple standards are being adopted for a single feature, it is recommended that both the standards are included in the feature instead of proposing a new standard. For example, if a Location schema is defined using gps and address, then the feature should include both gps and address instead of choosing one over the other. Standardization should occur as a natural consequence of market adoption rather than a forced adoption. -There will be exceptions to the above principles. The objective of the Core Working Group is to address such exceptions and define the most logical way forward to include such exceptions. +There will be exceptions to the above principles. The objective of the Core Working Group is to address such exceptions and define the most logical way to include such exceptions in the specification and clearly document those deviations. + +# Introduction +Beckn protocol is maintained via an open community-driven governance model. The community comprises multiple businesses and organizations that actively contribute to the specification to fuel their digital acceleration. This collaboration across domains, technologies and expertises will bring in new ideas which need to be part of the protocol. Hence there is a need for a standardised process for making relevant changes to the specification as well and for a retrospective understanding of the specification. The governance model for beckn protocol has been created using some of the best practices of globally recognized governance models. + +Evolution of beckn protocol is managed by committers of the **Core Working Group**. This working group consists of members from the **Beckn Open Community** that bring their architectural expertise, open-source knowledge, and industry experience to continuously review proposals to update the specification, and to also manage its releases. They constantly interact with the community members and incorporate their feedback, and also expand the group of committers as and when appropriate. -# Need for Governance +The Core Working Group holds weekly web conferences to review open pull requests and discuss open issues related to the evolving specification. Participation in weekly calls and scheduled working sessions is open to the community. -Since the core specification is essentially abstracted, the implementers of the specification must use instances of the core specification for various domains, regions and scope. Moreover, the Beckn Protocol specification is built by applying policies on the core specification. Hence, there is a need for a strong and inclusive governance model that adheres to the basic design principles while simultaneously being inclusive in its approach to evolution as opposed to a foundation-controlled evolution. +This governance model is inspired from the [OpenAPI ](https://www.openapis.org/participate/how-to-contribute/governance) Specification and IETF governance models. +## Need for Governance +Since the core specification is essentially abstracted, the implementors of the specification must use instances of the core specification for various domains, regions and scope. Moreover, the beckn protocol specification is implemented by applying policies on the core specification. Hence, there is a need for a strong and inclusive governance model that adheres to the basic design principles while simultaneously being inclusive in its approach to evolution as opposed to a foundation-controlled evolution. -# Areas That Require Specification Governance +## Areas That Require Specification Governance There are many independently governable specification elements in the Beckn Protocol. These elements are called areas. Each area will have multiple working groups under it. The following are the areas currently identified : +### Design Principles +Beckn protocol specification adopts a set of design principles that must be adhered to at all times while updating the specification. These principles, like all other principles, are not applicable for all time. Hence, the design principles must also allow themselves to evolve over time. Only then will the protocol be future-proof. The Core Working Group must: + +- Document the design principles in its purest and most unambiguous form +- Identify any overlaps between design principles, and find a way to make each principle atomic in its definition +- Define a methodology to apply each principle on various decision points related to the specification +- Create sufficient examples for each principle to allow contributors to self-apply the principles before proposing changes to the specification +- Periodically stress-test the design principles on the various components of the specification +- Record any violation of said design principles and report it to the violator with suggested changes + +### API +Beckn protocol defines a set of actions that may be implemented as APIs. The Core Working Group must: -* **API** : Core API and schema definitions -* **Taxonomy** : Domain-specific repositories for organization of taxonomies and taxonomy element definitions -* **Certification** : Certification and compliance rules and specifications -* **Architecture** : High level architecture definition and definitions of the various components in the network -* **Network Security** : Network security protocols and best practices -* **Policy** : Governance structures, licences and copyrights -* **Missions** : Specific implementation related working groups +- Clearly define the methods supported by the API +- Document the API in standard machine-readable formats like Open API, Async API or likewise +- Define methodologies to test the API against various use cases +- Extend the API to support more use cases +### Schema +Beckn protocol defines a standard schema that can be composed and instantiated as run-time objects. The Core Working Group must: + +- Clearly define the schema in an unambiguous manner +- Document the schema in standard formats like JSON Schema +- Define methodologies to test the schema against various use cases +- Extend the schema set to support more use cases via addition or extension +- Define methodologies to map any sector-specific knowledge model to the core schema + +### Communication +Beckn protocol defines a standard communication protocol for each API endpoint. The Core Working Group must: + +- Clearly define the exchange mechanism for each action via UML sequence diagrams +- Link the schema and API definition in each sequence +- Explain each interaction in simple terms +- Define methodologies to map real-world consumer-provider interactions to beckn protocol interactions + +### Architecture +Beckn protocol specifies a standard reference architecture of an open network. The network actors it currently includes are BAP, BPP, BG and a Network Registry. The Core Working Group must: + +- Document the ecosystem architecture in an unambiguous, machine-readable way. Using UML wherever possible +- Clearly define each layer of the architecture +- Clearly define the actors in each layer of the architecture +- To clearly define the purpose of each Network Actor +- To maintain an up-to-date, technology-agnostic, high-level reference implementation architecture document for each network actor +- To define processes to add new Network Actors to the specification +- Define processes to periodically evolve the architecture based on community contributions # Area Director (AD) @@ -170,21 +200,24 @@ The specification will evolve over time. Changes may be made when any of the fol # Specification Review Guidelines -While reviewing each change in the specification committers should always consider the following: +While reviewing each change in the Core Working Group should always consider the following: + +1. **Relevance**: Beckn protocol has defined clear boundaries on what is in-scope of beckn protocol and what is not. CWG members should ask themselves some basic questions like. Is it network-specific? Is it technology-specific? Is it implementation-specific? -1. **Migration Impact**: Is this a construct that has a smooth implementation path from the latest specification? If so, how complicated is it to migrate implementations to the proposed change? Secondly, how large of a cohort is affected due to this change -2. **Tooling**: Contributors should strive to support code generation, software interfaces, spec generation techniques, as well as other utilities. Some features may be impossible to support in different frameworks/languages. These should be documented and considered during the change approval process. -3. **Visualization**: Can the specification change be graphically visualized somehow in a UI or other interface +2. **Migration Impact**: Is this a construct that has a smooth implementation path from the latest specification? If so, how complicated is it to migrate implementations to the proposed change? Secondly, how large of a cohort is affected due to this change +3. **Tooling**: Contributors should strive to support code generation, software interfaces, spec generation techniques, as well as other utilities. Some features may be impossible to support in different frameworks/languages. These should be documented and considered during the change approval process. +4. **Visualization**: Can the specification change be graphically visualized somehow in a UI or other interface Spec changes should be approved by a majority of the committers. Approval can be given by commenting on the issue itself, for example, "Approved by @cwgadmin" however at least one formal GitHub-based flow approval must be given. After the voting criteria is met, the WG Admin can merge or assign a member to merge the PR. No change should be approved until there is documentation for it, supplied in an accompanying PR. # Feature Evolution -All new features have a life cycle starting from a proposal to a required standard. All new features to the specification must start with a status as “proposed”. Upon review, the CWG will decide to move forward with a discussion on the change and then move it to a “draft” status. If the feature is considered to become part of the specification, it will be moved to the “recommended” status. And if the feature is widely accepted and adopted by the ecosystem, then it will be moved to a “required” status after which it will become part of the core specification. - +All new features have a lifecycle starting from a proposal to a protocol standard. All new features to the specification must start with a status as “proposed”. Upon review, the CWG will decide to move forward with a discussion on the change and then move it to a “draft” status. If the feature is considered to become part of the specification, it will be moved to the “recommended” status. And if the feature is widely accepted and adopted by the ecosystem, then it will be moved to a “required” status after which it will become part of the core specification. All proposals to the specification are submitted as namespaced properties as mentioned in CONTRIBUTIONS.md. The working group has the responsibility of reviewing these proposals and classify them accordingly as draft, recommended, required or not-recommended features. Once classified, the WGs must rename the namespace with the appropriate feature stage component after review. +All development activity on the future specification will be performed as features on a draft branch and merged into this branch. Upon release of the future specification, this branch will be merged to master. + ## Proposal