k8s.io/kubernetes@v1.31.0-alpha.0.0.20240520171757-56147500dadc/api/api-rules/README.md (about)

     1  # Existing API Rule Violations
     2  
     3  This folder contains the checked-in report file of known API rule violations.
     4  The file violation\_exceptions.list is used by Make rule during OpenAPI spec generation to make
     5  sure that no new API rule violation is introduced into our code base.
     6  
     7  ## API Rule Violation Format
     8  
     9  The report file [violation\_exceptions.list](./violation_exceptions.list) is in format of:
    10  
    11   * ***API rule violation: \<RULE\>,\<PACKAGE\>,\<TYPE\>,\<FIELD\>***
    12  
    13  e.g.
    14  
    15   * ***API rule violation: names_match,k8s.io/api/core/v1,Event,ReportingController***
    16  
    17  And the violation list is sorted alphabetically in each of the \<RULE\>, \<PACKAGE\>, \<TYPE\>, \<FIELD\> levels.
    18  
    19  ## How to resolve API Rule Check Failure
    20  
    21  Make rule returns an error when the newly generated violation report differs from this
    22  checked-in violation report.
    23  
    24  Our goal is that exceptions should never be added to this list, only fixed and removed.
    25  For new APIs, this is a hard requirement. For APIs that are e.g. being moved between
    26  versions or groups without other changes, it is OK for your API reviewer to make an
    27  exception.
    28  
    29  If you're removing violations from the exception list, or if you have good
    30  reasons to add new violations to this list, please update the file using:
    31  
    32   - `UPDATE_API_KNOWN_VIOLATIONS=true ./hack/update-codegen.sh`
    33  
    34  It is up to API reviewers to review the list and make sure new APIs follow our API conventions.
    35  
    36  **NOTE**: please don't hide changes to this file in a "generated changes" commit, treat it as
    37  source code instead.
    38  
    39  ## API Rules Being Enforced
    40  
    41  For more information about the API rules being checked, please refer to
    42  https://github.com/kubernetes/kube-openapi/tree/master/pkg/generators/rules