Sub Projects
The CAMARA Project is organized primarily into Sub Projects. Each Sub Project is comprised of Project participants from multiple companies and organizations, with a common purpose of advancing the Sub Project with respect to a specific Service API topic, for example ‘quality on demand’ or ‘localization’. Our goal is to enable distributed decision making and code ownership. This will be done by providing focused forums for getting work done, making decisions, and onboarding new Contributors.
Areas covered by Sub Projects may be vertically focused on particular Service API components or functions, cross-cutting/horizontal or spanning many/all functional areas of Service APIs. Some examples of each type are:
- Vertical: Quality on Demand, Localization
- Horizontal: Scalability, Architecture, Lifecycle, Service
Each Sub Project is documented in a separate repository.
Each Sub Project must have a README.MD file (with a description of the Sub Project), a CODEOWNERS and a MAINTAINERS.MD file. A Sub Project should have at least one Maintainer. Ideally a SubProject is managed by two or more Maintainers, depending on the size and scope of the Sub Project. Here, the responsibilities must be clearly agreed upon between all of the Maintainers. This includes coordinating who is responsible for which issues and pull requests. The Contributors to a Sub Project are recorded by the mechanisms of GitHub in the Sub Project’s repository. Each Contributor, Codeowner and Maintainer should also be listed in the PARTICIPANTS.MD file in the root directory. Each Sub Project should have a license file, a GOVERNANCE.MD file (pointing to the Governance repository) and subdirectories /documentation, /code/API_code and /code/API_definitions. Writing permission to a Sub Project only codeowners should have.
Some Sub Projects may have distinct (although sometimes overlapping) sets of Contributors, Codeowners and Maintainers.
Where a Sub Project has a release process, access and documentation should be such that more than one person can perform a release. Releases should be announced on the CAMARA Project mailing list.
Working Groups
Working Groups are primarily used to facilitate topics of discussion that are in scope for the CAMARA Project but that are short-lived or that span multiple Sub Projects. If a subset of Project participants wants to get together and discuss a topic, they can do so with forming a Working Group. The Steering Committee decides upon implementing or removing working groups.
All Working Groups are documented in one GitHub repository “WorkingGroups” with a subfolder for each Working Group. Each Working Group must have a README.MD file (with a description of the working group) and a WG_PARTICIPANTS.MD file with the Working Group participants.
Repositories
As mentioned before the contributions to the Sub Projects were documented in the respective GitHub repositories of the Sub Projects, and the contributions to Working Groups were documented in the GitHub repository “WorkingGroups”. All contributions beyond that, esp. contributions to the Project itself or the the Steering Committee are documented in the GitHub repository “Governance”.
Use branches to reflect the artefact status
All Sub Projects and Working Groups have to work with 4 branches to reflect the status of the artefacts (API descriptions, API code, documentation, etc.):
- CON Branch for contributions
- WIP Branch for work-in-progress
- RTR Branch for artefacts which are ready-to-review
- main Branch for deliverables which can be shared externally
All contributions (e.g. initial files, tools, templates) to CAMARA have to be made only to the CON branch. If Project participants intend to start working on an topic first they have to copy the respective artefacts to the WIP branch. The original copy of the artefacts is kept in the CON branch.
In the WIP branch the real work takes place. If artefacts get ready for review these have to me moved from the WIP branch to the RTR branch. The artefacts in the WIP branch have to be removed. Technically, there is no such mechanism as "moving" between branches in GitHub. So files have to be copied/created in a parallel branch and have to be deleted from the original one.
In the RTR branch the review and inclusion of findings takes place. If artefacts are accepted by the Sub Project or Working Group these have to be moved/merged to the main branch. The artefacts on the RTR branch have to be removed.
For copying/moving/merging changes into a branch pull requests have to be initiated. For these pull requests a standardized naming target-branch_target-subject_user shall be used.
Mailing list
A Project mailing list is established, each Project participant documented in PARTICIPANTS.MD is added.
Project participants
Project participant (= contributor) status may be given to those who intend to make ongoing contributions to the CAMARA Project. This is usually in the form of code submissions and improvements and/or notable work on documentation but may also include other contributions such as organizing events or user support.
The current Project participants are listed in PARTICIPANTS.MD.
Please note that the CAMARA Project had received significant contributions from a number of unlisted individuals before this governance document was written, and thus formal team membership was created.
To be listed in PARTICIPANTS.MD is prerequisite for getting any other role in the Project. Also any other role within the Project has to be returned before deleting the name in PARTICIPANTS.MD.
Changes in Project participantship
A new Project participant can get Project participantship by adding his name to the PARTICIPANTS.MD file of the Project. Changes in Project participantship have to be announced on the CAMARA Project mailing list by the new participant. They are decided by lazy consensus .
A Project participant may resign by notifying the team mailing list and removing his name of the PARTICIPANTS.MD file. A Project participant with no project activity for a year is considered to have resigned. Project participants that wish to resign are encouraged to propose another Project participant to take over their project work.
Working Group participants
Each Project participant can be part of one or more of the Working Groups of the Project by adding his name to the WG_PARTICIPANTS.MD files. By that he gets the role Working Group participant.
A Working Group participant may resign by removing his name of the WG_PARTICIPANTS.MD file.
Contributors
Each Project participant can contribute to the Sub Projects of the Project. Contributors to a Sub Project can contribute by creating pull requests. There’s no formal process for becoming or resigning as Contributor. The list of Contributors of a specific Sub Project is maintained by GitHub.
Codeowners
Codeowners can merge code and accept pull requests. A Codeowner is responsible for the overall quality and stewardship of the Project. Contributors can get a Codeowner role if they are deeply involved in contributing code, pull request review, and triaging issues in the Sub Project for a minimum of three months and perform an ongoing contribution. Codeowners are decided by the Maintainers and formalized by changing the CODEOWNERS file. Changes in codeownership have to be announced on the CAMARA Project mailing list.
Maintainers
Maintainers are the leaders of a Sub Project. Maintainers are first and foremost contributors that have shown they are committed to the long-term success of a Sub Project. Contributors wanting to become Maintainers are expected to be deeply involved in contributing code, pull request review, and triaging issues in the Sub Project for a minimum of three months and perform an ongoing contribution.
Changes in maintainership
When creating a new Sub Project the Steering Committee also nominates the Maintainers for it. After that the Maintainers of a Sub Project decide upon the maintainership.
Changes in maintainership have to be announced on the CAMARA Project mailing list. They are decided by lazy consensus by all Maintainers of a Sub Project and formalized by changing the MAINTAINERS.MD file of the respective Sub Project.
A Maintainer may resign by notifying the Project mailing list. A Maintainer with no Project activity for a year is considered to have resigned. Maintainers that wish to resign are encouraged to propose another Project participant to take over their Project work.
Maintainer requirements
The following requirements must be met by an individual wishing to become a Maintainer for a Sub Project:
- Deep understanding of the technical goals and direction of the Sub Project
- Deep understanding of the technical domain of the Sub Project
- Sustained contributions to the design and direction of the Sub Project, demonstrated by performing all of the following:
- Authoring and reviewing proposals
- Initiating, contributing and resolving discussions (emails, GitHub issues, meetings)
- Identifying subtle or complex issues in designs and implementation pull requests
- Direct contributions to the Sub Project through implementation and / or review
Maintainer responsibilities
Maintainers lead one or more Sub Project(s) or parts thereof and serve as a point of conflict resolution amongst the Contributors and are the technical authority for a Sub Project (responsible for vision and direction and overall design, choose/approve change proposals, field technical escalations, etc.). They MUST have demonstrated both good judgement and responsibility towards the health of that Sub Project. Sub Project Maintainers MUST set technical direction and make or approve design decisions for their Sub Project - either directly, or through delegation of these responsibilities.
Maintainers are also intended to be organizers and facilitators, responsible for the continued operation and progress of the Sub Project and for communication and co-ordination with the other Sub Projects, the Steering Committee, and the Project participants.
Maintainers should actively participate in pull request reviews and are expected to respond to assigned pull requests in a reasonable time frame, either providing insights, or assign the pull requests to other Maintainers.
The following responsibilities must be met by the Maintainer for a Sub Project:
- Make and approve technical design decisions for the Sub Project.
- Set the technical direction and priorities for the Sub Project.
- Define milestones and releases.
- Mentor and guide Contributors and Codeowners to the Sub Project.
- Ensure continued health of Sub Project
- Adequate test coverage to confidently release
- Tests are passing reliably (i.e. not flaky) and are fixed when they fail
- Ensure a healthy process for discussion and decision making is in place and is followed by the Sub Project's Contributors.
- Work with other Sub Project owners to maintain the Project's overall health and success holistically.
How do I propose a decision?
Send an email to the CAMARA Project mailing list with your motion. If there is no objection within a reasonable amount of time (1 week after most recent meeting / email announcement of the decision), consider the decision made. If there are objections and no consensus can be found, a vote may be called by a Project participant.
How do I become a Project participant?
To become an official Project participant, you should intend to make ongoing contributions to one or more Sub Project(s). At that point you simply have to add your name to the PARTICIPANTS.MD file of the Project and announce it on the Project mailing list. A possible, but not required, graduation path is to become a Codeowner or a Maintainer later.
How do I add a Sub Project?
As a Project participant, propose the new Sub Project to the Steering Committee. If Steering Committee accepts, it creates the Sub Project in the GitHub repository. Add at least a README.MD explaining the description and the goal of the Sub Project, a CODEOWNERS and a MAINTAINERS.MD with the Maintainers of the Sub Project (at this point, this probably means you).
How do I archive or remove a Sub Project?
As a Project participant, propose the removal of a Sub Project to the Steering Committee. If Steering Committee accepts, stop all work in the Sub Project, but keep the documentation in the Sub Project’s repository (no archiving).
How do I remove an inactive Maintainer?
A Maintainer may resign by notifying the Project mailing list and remove his name from the MAINTAINERS.MD. A Maintainer with no Project activity for a year will be treated as if he had resigned.
How do I remove a Project participant?
Project participants may resign by notifying the Project mailing list and removing their names from PARTICIPANTS.MD.