sigs.k8s.io/prow@v0.0.0-20240503223140-c5e374dc7eb1/pkg/pluginhelp/pluginhelp.go (about)

     1  /*
     2  Copyright 2017 The Kubernetes Authors.
     3  
     4  Licensed under the Apache License, Version 2.0 (the "License");
     5  you may not use this file except in compliance with the License.
     6  You may obtain a copy of the License at
     7  
     8      http://www.apache.org/licenses/LICENSE-2.0
     9  
    10  Unless required by applicable law or agreed to in writing, software
    11  distributed under the License is distributed on an "AS IS" BASIS,
    12  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13  See the License for the specific language governing permissions and
    14  limitations under the License.
    15  */
    16  
    17  // Package pluginhelp defines structures that represent plugin help information.
    18  // These structs are used by sub-packages 'hook' and 'externalplugins'.
    19  package pluginhelp
    20  
    21  // Command is a serializable representation of the command information for a single command.
    22  type Command struct {
    23  	// Usage is a usage string for the command.
    24  	Usage string
    25  	// Featured is a flag for featured/highlight plugins.
    26  	Featured bool
    27  	// Description is a short description about what does the command do.
    28  	Description string
    29  	// Examples is a list of usage example for the command.
    30  	Examples []string
    31  	// WhoCanUse is a description of the permissions/role/authorization required to use the command.
    32  	// This is usually specified as a github permissions, but it can also be a github team, an
    33  	// OWNERS file alias, etc.
    34  	// This field may include HTML.
    35  	WhoCanUse string
    36  }
    37  
    38  // PluginHelp is a serializable representation of the help information for a single plugin.
    39  // This includes repo specific configuration for every repo that the plugin is enabled for.
    40  type PluginHelp struct {
    41  	// Description is a description of what the plugin does and what purpose it achieves.
    42  	// This field may include HTML.
    43  	Description string
    44  	// Config is a map from org/repo strings to a string describing the configuration for that repo.
    45  	// The key "" should map to a string describing configuration that applies to all repos if any.
    46  	// This configuration strings may include HTML.
    47  	Config map[string]string
    48  	// Snippet is a snippet of yaml for delineating configuration for the plugin.
    49  	Snippet string `json:",omitempty"`
    50  	// Events is a slice containing the events that are handled by the plugin.
    51  	// NOTE: Plugins do not need to populate this. Hook populates it on their behalf.
    52  	Events []string
    53  	// Commands is a list of available commands of the plugin.
    54  	Commands []Command
    55  }
    56  
    57  // Help is a serializable representation of all plugin help information.
    58  type Help struct {
    59  	// AllRepos is a flatten (all org/repo, no org strings) list of the repos that use plugins.
    60  	AllRepos []string
    61  	// RepoPlugins maps org and org/repo strings to the plugins configured for that scope.
    62  	// NOTE: The key "" maps to the list of all existing plugins (including failed help providers).
    63  	// A mix of org or org/repo strings is desirable over the flattened form (all org/repo) that
    64  	// 'AllRepos' uses because it matches the plugin configuration and is more human readable.
    65  	RepoPlugins         map[string][]string
    66  	RepoExternalPlugins map[string][]string
    67  	// PluginHelp is maps plugin names to their help info.
    68  	PluginHelp         map[string]PluginHelp
    69  	ExternalPluginHelp map[string]PluginHelp
    70  }
    71  
    72  // AddCommand registers new help text for a bot command.
    73  func (pluginHelp *PluginHelp) AddCommand(command Command) {
    74  	pluginHelp.Commands = append(pluginHelp.Commands, command)
    75  }