User Story

As a developer adding new APIs to OpenShift I want to have written documentation about the conventions that my new API must adhere to so that I can design my API in a compliant way, to ease the process of review.

Background

As an API reviewer, a lot of things come up repeatedly, we should document these things so that we have a reference for contributors to read so that they ideally, adhere to the conventions before the API reviewers get to them.

Steps

• Add notes to the API conventions doc in regards to the following topics:
  • Not using reference types
  • How to use defaulting - different kinds
  • Unions - when to use, how to use, caveats
  • Deprecation
  • Configuration APIs vs User facing APIs
  • Not repeating sins of the past
  • Using Kube conventions over Cloud provider conventions

Stakeholders

• API reviewers
  • Joel Speed
  • David Eads
  • Other API reviewers
• API authors

Definition of Done

• All subtasks have been completed

• Docs

• N/A

• Testing

• N/A