# Programmatic OpenShift Organizational Structure

A YAML file in a private github repository is used to track team structure.
The data is intended to provide reliable and efficient team contact by automation
and by users unfamiliar with the OpenShift structure.

Periodic processes, using this data as a source of truth, update:
- The team tracking spreadsheet.
- An organization diagram showing pillars & groups.
- Slack aliases for the team.
- Github org/repo/team membership and authorization

For human UX, a Slack bot will be made available:

@openshift-org-bot
> search oc
Teams relevant to your search:
OpenShift Workloads
- Matches repository: github.com/openshift/<bold>oc</bold>.  
- Matches keyword: "<bold>oc</bold> client"


> describe OpenShift Workloads
Team: OpenShift Workloads
Description: <team description>
Jira project -> https://issues.redhat.com/projects/WRKLDS
Open a bug -> https://issues.redhat.com/secure/CreateIssueDetails!init.jspa?...component=oc
Slack Forum -> ...
Team Members:
- ..  (Team Lead)
- ..
Staff Engineers:
- ..
Managers:
- ..
How to contact the team:
<team's contact protocol...>

Example schema entry.

schema: 1


# A flexible org structure which is sufficient
# to render a straightforward org diagram.
structures:
- type: org
  id: openshift
  name: OpenShift
  staff_engineers:
  - bparees
  - dhellmann
  
  structures:
  - type: pillar
    id: saf
    name: "Services and Fleets"
    description: ...
    managers:
    - nstielau
    staff_engineers:
    - sdodson
    - mpatel
    
    structures:
    - type: group
      id: ship
      name: "SHIP"
      description: ...
      managers:
      - bleanhar
      staff_engineers: 
      - jupierce
      
      structures:
      - type: team
        # Futher detail about each team can be found in the 'teams:' stanza.
        id: testplatform
        name: "Test Platform"
        managers:
        - ppawlows
        team_leads:
        - jguzik
        

          

teams:            
- id: testplatform
  type: engineering
  
  description: The Test Platform team builds and operates a suite of OpenShift-native tooling and infrastructure for testing and continuous integration of OpenShift and layered products.
  
  contact_protocol: |
  <The team's description of how to contact them in specific situations. 
  Can include hyperlinks to source pages>.
  
  # Allow users to search for teams based on
  # what they need.
  keywords:
  - prow
  - ci
  - continuous integration
  - testing
  - merge requirements
  - dptp

  people:
      include:
      - # Team membership information will primarily be 
        # sourced from LDAP so that this file does not need
        # frequent updates.
        id: "ldap_group:rover_group_that_contains_all_team_members"
  
  documents:
  - name: "Architecture Call"
    link: https://docs.google.com/document/d/1qscKvou44...

  associations:
  - type: px
    id: "structure:<id from somewhere in the structure stanza>"
  - type: qe
    id: "team:..."
  - type: agile
    id: nwilker
  - type: pm
    ...
  - type: docs
    ...

  slack:             
      channels:
      - type: team  # Private channel that is automatically setup to include team.people
        name: team-dp-testplatform
        people:
          include:
          - "structure:testplatform"
          - jupierce
          - "cohort:honorary_testplatform"
      - type: forum
        name: forum-testplatform

      # Teams can have automatically managed Slack aliases
      # populated from ldap, structures, or cohorts.
      aliases: 
      - type: contact
        name: team-testplatform
        people:
          include:
          - id: "ldap_group:rover_group_that_contains_all_team_members"
          exclude:
          - id: example_individual_uid
      - type: helpdesk  # Optional handle (team maintained) for on call questions.
        name: dptp-helpdesk
      - type: triage   # Optional handle (team maintained) for urgent assistance.
        name: dptp-helpdesk


  email:
      # Mailing list with all team members
      # and manager. Automatically reconciled by CRT
      # on rover group changes.
      team_list: ...


  jira: 
      project: DPTP

  software_components:
  - name: "Core"
    repos:
    - name: github.com/openshift/release
    - name: github.com/openshift/ci-tools
    bugs:
      jira_project: "OCPBUGS"
      jira_component: "Test Infrastructure"


# Peribolos ultimately translates into a periobolos github configuration which 
# will control membership and authorization for orgs/repos/teams.
# It matches the peribolos schema, https://docs.prow.k8s.io/docs/components/cli-tools/peribolos/ ,
# but allows symbolic references to teams, structures, and cohorts.
peribolos:
    github:
      orgs:
          openshift-priv:
              admins:
              - "team:art"

          openshift:
              admins:
              - "cohort:staff_engineers"
              members:
              - "structure:openshift"
              - "cohort: roks_ibmers"
              teams: 
                  "OpenShift ART Team":
                      members:
                      - "team:art"
                  "OpenShift TestPlatform":
                      members:
                      - "team:testplatform"


# Cohorts are not as structured a teams, but can carry similar information.
# They can be composed of individual members, other cohorts, or teams.
# Teams can likewise reference cohorts as a source of people.
cohorts:
- id: container_runtime_smes
  description: ...
  keywords:
  - podman
  - crio
  - ...
  people:
    include:
    ...
    exclude:
    ...
- id: roks_ibmers
  description: ...
  keywords:
  - ...
  people:
    include:
    - id: "external:ibmer1"
    - id: "external:ibmer2"
              

# Externals allows non-Red Hatters to be represented. This is primarily
# to allow them to be members of github orgs & teams.
externals:
- id: ibmer1
  email: ...
  github: ...
  slack: ...
  role: ...
  valid_through: ...
  
  

Periodic processes validate (and alert CRT when invalid):
- Rover groups are populated with employees.
- Jira components exist.

Misc:
- There will be a CI pre-submit to validate changes to the data against a schema.
- Data in the files would support (or eventually drive) github repo privileges, root OWNERS file, etc.