.. _project_roles:

TSC Project Roles
*****************

Overview
########

TSC projects generally will involve *Maintainers*, *Collaborators*, and
*Contributors*:

**Maintainer**: lead Collaborators on an area identified by the TSC (e.g.
Architecture, code subsystems, etc.). Maintainers shall also serve as the
area’s representative on the TSC as needed.  Maintainers may become voting
members of the TSC by approval of the existing TSC voting members.

**Collaborator**: A highly involved Contributor in one or more areas.
May become a Maintainer with approval of existing TSC voting members.

**Contributor**: anyone in the community that contributes code or
documentation to the project. Contributors may become Collaborators
by approval of the existing Collaborators and Maintainers of the
particular code base areas or subsystems.


Contributor
###########

A *Contributor* is a developer who wishes to contribute to the project,
at any level. Contributors who show dedication and skill are rewarded with
additional rights and responsibilities.

Contributors are granted the following rights and responsibilities:

* Right to contribute code, documentation, translations, artwork, etc.
* Right to report defects (bugs) and suggestions for enhancement.
* Right to participate in the process of reviewing contributions by others.
* Right to initiate and participate in discussions in any communication
  methods.
* Right to approach any member of the community with matters they believe
  to be important.
* Right to participate in the feature development process.
* Responsibility to abide by decisions, once made. They are welcome to
  provide new, relevant information to reopen decisions.
* Responsibility for issues and bugs introduced by one’s own contributions.
* Responsibility to respect the rules of the community.
* Responsibility to provide constructive advice whenever participating in
  discussions and in the review of contributions.
* Responsibility to follow the project’s code of conduct
  (https://github.com/zephyrproject-rtos/zephyr/blob/master/CODE_OF_CONDUCT.md)

Collaborator
############

A *Collaborator* is a Contributor who is also responsible for the maintenance
of Zephyr source code. Their opinions weigh more when decisions are made, in a
fully meritocratic fashion.

Collaborators have the following rights and responsibilities,
in addition to those listed for Contributors:

* Right to set goals for the short and medium terms for the project being
  maintained, alongside the Maintainer.
* Responsibility to participate in the feature development process.
* Responsibility to review relevant code changes within reasonable time.
* Responsibility to ensure the quality of the code to expected levels.
* Responsibility to participate in community discussions.
* Responsibility to mentor new contributors when appropriate
* Responsibility to participate in the quality verification and release
  process, when those happen.

Maintainer
##########

A *Maintainer* is a Collaborator who is also responsible for knowing,
directing and anticipating the needs of a given zephyr source code area.

Maintainers have the following rights and responsibilities,
in addition to those listed for Contributors and Collaborators:

* Right to set the overall architecture of the relevant subsystems or areas
  of involvement.
* Right to make decisions in the relevant subsystems or areas of involvement,
  in conjunction with the collaborators.
* Responsibility to convey the direction of the relevant subsystem or areas to
  the TSC
* Responsibility to ensure all contributions of the project have been reviewed
  within reasonable time.
* Responsibility to enforce the code of conduct.


Teams and Supporting Activities
*******************************

Assignee
########

An *Assignee* is one of the maintainers of a subsystem or code being changed.
Assignees are set either automatically based on the code being changed or set
by the other Maintainers, the Release Engineering team can set an assignee when
the latter is not possible.

* Right to dismiss stale reviews and seek reviews from additional maintainers,
  developers and contributors
* Right to block pull requests from being merged
* Responsibility to re-assign a pull request if they are the original submitter
  of the code
* Responsibility to drive the pull request to a mergeable state
* Solicit approvals from maintainers of the subsystems affected
* Responsibility to drive the escalation process

Release Engineering Team
########################

A team of active Maintainers involved in multiple areas.
The team is appointed by the TSC and reports directly into the TSC.
Release Engineering team has the following rights and responsibilities:

* Right to merge code changes to the zephyr tree following the project rules.
* Right to revert any changes that have broken the code base
* Right to close any stale changes after <N> months of no activity
* Responsibility to take directions from the TSC and follow them.
* Responsibility to coordinate code merges with maintainers.
* Responsibility to merge all contributions regardless of their
  origin and area if they have been approved by the respective
  maintainers and follow the merge criteria of a change.
* Responsibility to keep the Zephyr code base in a working and passing state
  (as per CI)


Release Activity
################

.. figure:: img/img_release_activity.png
     :width: 663px
     :align: center
     :alt: Release Activity


MAINTAINERS File
################

Generic guidelines for deciding and filling in the Maintainers' list

* The MAINTAINERS file shall coexist with the CODEOWNERS file.
  MAINTAINERS file is used to set assignees, CODEOWNERS file is used for
  more granularity and to add reviewers down to the file level.
  CODEOWNERS file entries do not signify maintainership.
* We should keep the granularity of code maintainership at a manageable level
* We should be looking for maintainers for areas of code that
  are orphaned (i.e. without an explicit maintainer)

  * Un-maintained areas should be indicated clearly in the MAINTAINERS file

* All submitted pull-requests should have an assignee
* We Introduce an area/subsystem hierarchy to address the above point

  * Parent-area maintainer should be acting as default substitute/fallback
    assignee for un-maintained sub-areas
  * Area maintainer gets precedence over parent-area maintainer

* Pull-requests may be re-assigned if this is needed or more appropriate

  * Re-assigned by original assignee (see “Assignee” slide)

* Updates to the MAINTAINERS file should be in a standalone PRs
* The MAINTAINERS file itself shall have a maintainer
* Architectures, core components, sub-systems, samples, tests

  * Each area shall have an explicit maintainer

* Boards (incl relevant samples, tests), SoCs (incl DTS)
  * May have a maintainer, shall have a higher-level platform maintainer
* Drivers

  * Shall have a driver-area (and API) maintainer
  * Could have individual driver implementation
    maintainers but preferably collaborator/contributors
  * In the above case, platform-specific PRs may be
    re-assigned to respective collaborator/contributor of driver
    implementation


Merge Criteria
##############

* All continuous integration checks have passed

  * Codeowners
  * Device Tree
  * Documentation
  * Gitlint
  * Identity/Emails
  * Kconfig
  * License
  * Checkpatch (Coding Style)
  * Pylint
  * Sanitycheck + Other Unit tests
  * Simulated Bluetooth Tests

* Planned

  * Footprint
  * Code coverage
  * Coding Guidelines
  * Static Analysis (Coverity)
  * Documentation coverage (APIs)

* PR template with checklist

* Minimal of 2 approvals

  * A collaborator from the same subsystem.
  * Alternately another maintainer of another subsystem
  * Approval by the assignee

* A minimum review period of 2 days, 4 hours for trivial changes (see
  :ref:`review_time`). Hotfixes can be merged at any time after CI passes.
* All required checks are passing

Escalation Process
##################

* Contributors may object to change requests or decisions made by
  Maintainers.
* Process

  * Resolve in the PR among assignee, maintainers and reviewer

    * Assignee to act as moderator if applicable

  * Optionally resolve in the dev review meeting with more Maintainers
    and project stakeholders

    * The involved parties and the Assignee to be present when
      the (escalated) issue is discussed

  * TSC: Assignees can escalate to the TSC voting members and get
    a binding resolution in the TSC.
  * Assignee to ensure the resolution of the escalation is
    reflected in the PR review.


Release Manager
###############

A *Maintainer* responsible for driving a specific release to
completion following the milestones and the roadmap of the
project for this specific release.

* TSC has to approve a release manager.

A Release Manager joins the release engineering team and has
the rights and responsibilities of that team in addition to
the following:

* Right to manage and coordinate all code merges after the
  code freeze milestone (M3, see `program management overview <https://wiki.zephyrproject.org/Program-Management>`_.)
* Responsibility to drive and coordinate the triaging process
  for the release
* Responsibility to create the release notes of the release
* Responsibility to notify all stakeholders of the project,
  including the community at large about the status of the
  release in a timely manner.
* Responsibility to coordinate with QA and validation and
  verify changes either directly or through QA before major
  changes and major milestones.

Roles / Permissions
###################

.. table:: Project Roles vs Github Permissions
    :widths: 20 20 10 10 10 10 10
    :align: center

    ================ =================== =========== ================ =========== =========== ============
          ..             ..               **Admin**  **Merge Rights**   Member      Owner     Collaborator
    ---------------- ------------------- ----------- ---------------- ----------- ----------- ------------
    Main Roles       Contributor                                                                 x
    ---------------- ------------------- ----------- ---------------- ----------- ----------- ------------
        ..           Collaborator                                       x
    ---------------- ------------------- ----------- ---------------- ----------- ----------- ------------
        ..           Maintainer                                         x
    Supportive Roles QA/Validation                                      x                        x
        ..           DevOps                   **x**
        ..           System Admin             **x**                                      x
        ..           Release Engineering      **x**      **x**          x

    ================ =================== =========== ================ =========== =========== ============