From 2a173fe7e95db03fc199caf696eac097280bc9c5 Mon Sep 17 00:00:00 2001 From: Doug Davis Date: Thu, 20 Sep 2018 13:31:55 -0400 Subject: [PATCH] Minor tweaks to our governance docs (#309) - Just writing down what we do/have today - We're not a WG, we're a sandbox project so I tried to remove all references to us being a WG (I left the refs to the Serverless WG though) - wrapped some stuff at 80 cols - replaced some tabs with spaces, because tabs are evil Signed-off-by: Doug Davis --- GOVERNANCE.md | 50 +++++++++++++++++++++++++++------------ OWNERS | 6 +++++ README.md | 10 ++++---- community/contributors.md | 6 ++--- primer.md | 18 +++++++------- roadmap.md | 22 ++++++++++------- share/README.md | 2 +- 7 files changed, 72 insertions(+), 42 deletions(-) create mode 100644 OWNERS diff --git a/GOVERNANCE.md b/GOVERNANCE.md index f88b70198..6e88e1f7c 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -1,32 +1,52 @@ # Governance -This document describes the governance process under which the Serverless -Working Group (WG) will manage this repository. +This document describes the governance process under which the CloudEvents +project will manage this repository. -## Working Group Meetings +## Meetings -In order to provide equitable rights to all Working Group members, +In order to provide equitable rights to all members, the following process will be followed: -* Official WG conference calls will be announced at least a week in advance. -* Official WG face-to-face meetings will be announced at least 4 weeks in +* Official conference calls will be announced at least a week in advance. +* Official face-to-face meetings will be announced at least 4 weeks in advance. * Proposed changes to any document will be done via a Pull Request (PR). -* PRs will be reviewed during official WG meetings. +* PRs will be reviewed during official meetings, but off-line reviews + (LGTMs, NOT LGTMs) and comments are strongly encouraged to gauge the + group's opinion on the proposed change prior to the meeting. * During meetings, priority will be given to PRs that appear to be ready for a vote over those that appear to require discussions. * PRs should not be merged if they have had substantial changes made within two days of the meeting. Rebases, typo fixes, etc. do not count as substantial. - Note, administrivia PRs that do not materially modify WG output documents - may be processed by WG admins as needed. + Note, administrivia PRs that do not materially modify output documents + may be processed by admins as needed. * Resolving PRs ("merging" or "closing with no action") will be done as a - result of a motion made during a WG meeting, and approved. + result of a motion made during a meeting, and approved. * Reopening a PR can be done if new information is made available, and a motion to do so is approved. * Any motion that does not have "unanimous consent" will result in a formal vote. See [Voting](#voting). +## Membership + +There are three categories of project membership: +1 - Member. This is anyone who participates in the group's activities in any + of our communication channels (email, github issues/PRs, meetings, etc.). + No formal registration process is needed. +2 - Voting Member. See the (Voting)[#voting]section below for more information + on how the list of Voting Members are determined. During the normal + operations of the group, Voting Members and Members are the same with + respect to influence over the groups actions. The rights associated with + being a Voting Member only apply in the event of a formal vote being taken. +3 - Admins. Admins are Members of the group but have the ability to perform + administrative actions on behalf of the group. For example, manage the + website, github repos and moderate the meetings. Their actions should + be done with the knowledge and consent of the group. They also have the + ability to merge/close PRs, but only per the group's approval. See + the [OWNERS](OWNERS) file for the current list of Admins. + ## PRs Typically, PRs are expected to meet the following criteria prior to being @@ -41,14 +61,14 @@ merged: ## Voting -If a vote is taken during a WG meeting, the follow rules will be followed: +If a vote is taken during a meeting, the follow rules will be followed: * There is only 1 vote per participating company, or nonaffiliated individual. * Each participating company can assign a primary and secondary representative. * A participating company, or nonaffiliated individual, attains voting rights by having any of their assigned representative(s) attend 3 out of the last 4 meetings. They obtain voting rights after the 3rd meeting, not during. -* Only WG members with voting rights will be allowed to vote. +* Only members with voting rights will be allowed to vote. * A vote passes if more than 50% of the votes cast approve the motion. * Only "yes" or "no" votes count, "abstain" votes do not count towards the total. @@ -78,8 +98,8 @@ To create a new release: * Release title should be the same as the Tag - `vX.Y` * Add some descriptive text, or the list of PRs that have been merged since the previous release. - The git query to get the list commits since the last release is: - `git log --pretty=format:%s master...v0.1`. - Just replace "v0.1" with the name of the previous release. + The git query to get the list commits since the last release is: + `git log --pretty=format:%s master...v0.1`. + Just replace "v0.1" with the name of the previous release. * Press `Publish release` button diff --git a/OWNERS b/OWNERS new file mode 100644 index 000000000..bbf41e579 --- /dev/null +++ b/OWNERS @@ -0,0 +1,6 @@ +# This file contains the current list of "Admins" for the CloudEvents +# group. See the GOVERNANCE.md document for more information on their +# roles and responsibilities. +- duglin +- markpeek +- kenowens12 diff --git a/README.md b/README.md index d72c50eb3..31510ecb4 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ The following specifications are available: There is also the [CloudEvents documented extension attributes](https://github.com/cloudevents/spec/blob/master/documented-extensions.md) document and a [CloudEvents Primer](primer.md) to help understand some of -the history and design goals of the working group. +the history and design goals of the project. ## Community @@ -51,16 +51,16 @@ us get started or are actively working on the CloudEvents specification. something to share about your use of CloudEvents, please submit a PR! -## Working Group process +## Process -The CNCF Serverless WG is working to formalize the [specification](spec.md) +The CloudEvents project is working to formalize the [specification](spec.md) based on [design goals](primer.md#design-goals) which focus on interoperability between systems which generate and respond to events. -In order to achieve these goals, the Serverless WG must describe: +In order to achieve these goals, the project must describe: - Common attributes of an *event* that facilitate interoperability - One or more common architectures that are in active use today or planned to - be built by WG members + be built by its members - How events are transported from producer to consumer via at least one protocol - Identify and resolve whatever else is needed for interoperability diff --git a/community/contributors.md b/community/contributors.md index 1b7b8ac1f..d4c2edb79 100644 --- a/community/contributors.md +++ b/community/contributors.md @@ -1,11 +1,11 @@ ## CloudEvents contributors We welcome you to join us! This list acknowledges those who contribute whether -it be via GitHub pull request or in real life in the working group, as well as -those who contributed before this became a CNCF Serverless WG project. If you +it be via GitHub pull request or in real life in the project, as well as +those who contributed before this became a CNCF project. If you are participating in some way, please add your information via pull request. -This list is intended to build community, helping the working group to connect +This list is intended to build community, helping the project to connect github handles to real world identities and get to know each other, and for new folks to see who has been involved already. diff --git a/primer.md b/primer.md index 3f90fc5a6..ea0e49e04 100644 --- a/primer.md +++ b/primer.md @@ -124,20 +124,20 @@ The following will not be part of the specification: ## CloudEvent Attribute Extensions -In order to achieve the stated goals, the working group will attempt to +In order to achieve the stated goals, the specification authors will attempt to constrain the number of metadata attributes they define in CloudEvents. To -that end, attributes defined by this working group will fall into three - categories: +that end, attributes defined by this project will fall into three +categories: - required - optional - extensions As the category names imply, "required" attributes will be the ones that -the working group considers vital to all events in all use cases, while +the group considers vital to all events in all use cases, while "optional" ones will be used in a majority of the cases. Both of the attributes in these cases will be defined within the specfication itself. -When the working group determines that an attribute is not common enough to +When the group determines that an attribute is not common enough to fall into those two categories but would still benefit from the level of interoperability that comes from being well-defined, then they will be placed into the "extensions" category and put into @@ -146,7 +146,7 @@ The specification defines how these extension attributes will appear within a CloudEvent. In determining which category a proposed attribute belongs, or even if it -will be included at all, the working group uses use-cases and +will be included at all, the group uses use-cases and user-stories to explain the rationale and need for them. This supporting information will be added to the [Prior Art](#prior-art) section of this document. @@ -225,7 +225,7 @@ protocol binding, it must belong to either one of the following categories: Aside from formal status, a key criterion for whether a protocol or encoding shall qualify for a core CloudEvents event format or transport binding is -whether the working group agrees that the specification will be of sustained +whether the group agrees that the specification will be of sustained practical benefit for any party that is unrelated to the product or project from which the protocol or encoding emerged. A base requirement for this is that the protocol or encoding is defined in a fashion that allows alternate @@ -237,7 +237,7 @@ respective project's own public repository or site. ## Prior Art -This section describes some of the input material used by the working group +This section describes some of the input material used by the group during the development of the CloudEvent specification. ### Roles @@ -504,7 +504,7 @@ instance to the correct application/workflow instance. ### Existing Event Formats As with the previous section, the examination (and understanding) of the -current state of the world was very important to the working group. To that +current state of the world was very important to the group. To that end, a sampling of existing current event formats that are used in practice today was gathered. diff --git a/roadmap.md b/roadmap.md index 8f2cea8b7..c134959b7 100644 --- a/roadmap.md +++ b/roadmap.md @@ -2,7 +2,8 @@ The CloudEvents Roadmap. -_Note: The ordered lists for each milestone provide a way to reference each item; they don't imply an order for implementation._ +_Note: The ordered lists for each milestone provide a way to reference each +item; they don't imply an order for implementation._ *Setup* @@ -13,16 +14,18 @@ _Note: The ordered lists for each milestone provide a way to reference each item *0.1* -1. Draft specification that WG members agree *could* provide interoperability. +1. Draft specification that project members agree *could* provide + interoperability. 1. Include an initial set of use-cases for CloudEvents. 1. Define a type system for CloudEvents values. 1. Document at least 3 sample events that conform to the specification. 1. Github repo is organized to be approachable to a engineers who might want to implement the spec. 1. Finalize logo. -1. Create and deploy a website that features a simple overview, email list and directs visitors to Github. +1. Create and deploy a website that features a simple overview, email list and + directs visitors to Github. 1. Store all website assets in the CloudEvents repository, under the governance -of the working group. + of the project. 1. Have at least 2 implementations of the specification that can demonstrate interoperability. 1. Include a specification for mapping the CloudEvents specification to @@ -34,10 +37,10 @@ of the working group. ([CloudNativeCon Europe](https://events.linuxfoundation.org/events/kubecon-cloudnativecon-north-america-2018/)). 1. Interoperability demo. 1. At least one open source implementation of sending and receiving - events, see - [community open source](https://github.com/cloudevents/spec/blob/master/community/open-source.md). + events, see + [community open source](https://github.com/cloudevents/spec/blob/master/community/open-source.md). 1. Events are sent by code written by Developer1 and received by code - written by Developer2, where Developer1 has no knowledge of Developer2. + written by Developer2, where Developer1 has no knowledge of Developer2. *0.2* @@ -48,7 +51,7 @@ of the working group. 1. Resolve all known "proposed required attributes" issues 1. Interoperability demo 2 1. Details to be determined - 1. Showcase demo at conferences - perhaps KubeCon NA 2018 + 1. Showcase demo at conferences - perhaps KubeCon NA 2018 1. Define the set of protocol and serialization mappings we're going to produce for 0.4 milestone @@ -60,7 +63,8 @@ of the working group. 1. Consider context size limits 1. Consider restricting character sets of `String` properties or key names 1. Consider defining uniqueness constraints of `eventId` - 1. Consider which fields will be immutable (prevents annotation or redaction) + 1. Consider which fields will be immutable (prevents annotation or + redaction) 1. Consider validating transport bindings with load tests *0.4* diff --git a/share/README.md b/share/README.md index 73c305cde..fd33479f0 100644 --- a/share/README.md +++ b/share/README.md @@ -1,4 +1,4 @@ -Directory to hold material that WG members wish to share with each other - +Directory to hold material that project members wish to share with each other - e.g. presentations from meetings or from conferences. These documents have no official standing within the group. References from this README to the documents can point to files stored