ra/1.1: adopt OCF RA API version 1.1

The main goals of this revision are to formalize existing widespread practice
that deviates from or extends the 1.0 standard, and to add optional new
meta-data hints that user interfaces can benefit from.

Changes from the 1.0 standard:

* Much of the document has been reworded and reorganized for consistency and
  clarity.

* The official home of the standard has been changed from opencf.org to
  github.com/ClusterLabs.

* The version number is now 1.1. (Obviously.)

* Resource types (agent names) should be suitable for use as a file name.

* Resource types and provider names that start with a dot (.) are a hint
  that the item should be omitted from lists provided to users.

* The resource agent directory, which could only be /usr/ocf/resource.d in 1.0,
  is now left to installers. Resource managers may search multiple directories.

* The resource agent meta-data syntax is now described in greater detail, and
  the schema is provided in RNG format rather than DTD. Changes in meta-data
  syntax:

  * The resource agent itself may have longdesc and shortdesc elements
    (previously, only parameters did).

  * It is now discouraged to use XML within longdesc, shortdesc, and desc,
    and instead limit the content to a text string.

  * The "unique" attribute is deprecated, and replaced with two new, optional
    attributes: "unique-group" is a hint that the combination of all parameters
    with the same value should be unique to the resource type, and "reloadable"
    is a hint that changes in the parameter can be made to take effect with the
    new, optional "reload-agent" action instead of a full stop and start.

  * The new "required" attribute may be given as a hint as to whether the
    user must specify the parameter.

  * The new "deprecated" child element is a hint that a parameter is deprecated
    and supported for backward compatibility only. It may contain zero or more
    "replaced-with" child elements to indicate parameters that should be used
    instead.

  * Parameter content elements may now have a type of "select", in which case
    it must have one or more "option" subelements listing specifically allowed
    values for the parameter.

  * The "special" element is now optional.

* Changes in resource actions (besides "reload-agent" mentioned above):

  * Resource agents may optionally support the new notify action to coordinate
    multiple instances of the service running simultaneously in a cluster.
    The exact behavior is left to resource managers and agents, but may be
    clarified in a future version.

  * Resource agents may optionally support two modes of operation, called
    roles, named "unpromoted" and "promoted". The new promote action brings a
    service to the promoted role, and the start action and new demote action
    bring it to the unpromoted role.

    The role names were chosen to be service-agnostic (unlike master/slave,
    primary/secondary, controller/worker, etc.). The unpromoted role was not
    named demoted, to avoid implying that a particular instance was previously
    promoted (it may have been started in the unpromoted role and never
    promoted). The unpromoted role was not named base, default, or standard
    because those are vague and could be easily misunderstood when context is
    unavailable.

  * Resources may now define any arbitrary actions as desired, as well as
    the mandatory and optional actions whose behavior is described by the
    standard.

* Changes in environment variables:

  * Resource managers and agents may optionally support the OCF_OUTPUT_FORMAT
    environment variable to select a format to be used (such as "text" or
    "xml") for user output.

  * Resource agents may optionally use the existing OCF_CHECK_LEVEL environment
    variable with meta-data actions (as well as monitor, as before). With
    meta-data, an OCF_CHECK_LEVEL of 0 or unspecified indicates internal
    consistency of parameters only, without regard to the local environment,
    while an OCF_CHECK_LEVEL of 10 may additionally verify the suitability of
    the local environment.

* Changes in exit statuses:

  * Resource agents are recommended, but not required, to use exit status 2 for
    parameters that are invalid in the context of the local host (such as a
    nonexistent configuration file), and exit status 6 for parameters that are
    internally invalid (such as a string given where only an integer is
    allowed).

  * New exit statuses have been defined: 8 for properly running in the promoted
    role, 9 for failed in the promoted role, 190 for properly running but
    degraded, and 191 for properly running in the promoted role but degraded.

  * No undefined exit statuses are reserved.

* The "to-do list" has been removed.

ra/1.1/resource-agent-api.md

@@ -21,9 +21,7 @@ shared by any such software.
 This is an Open Cluster Framework (OCF) document produced by ClusterLabs
 <https://clusterlabs.org>.
 
-This document is a proposed draft of the 1.1 version of the OCF RA API. It has
-not yet been adopted as a standard, and should be considered for discussion
-purposes only.
+This document describes version 1.1 of the OCF RA API standard.
 
 
 ## Copyright Notice