Merge pull request container-storage-interface#325 from saad-ali/fixM…

…ayMust

Scrub spec for "should", "must", etc. and capitalize

csi.proto

@@ -118,7 +118,7 @@ message PluginCapability {
 
       // CONTROLLER_SERVICE indicates that the Plugin provides RPCs for
       // the ControllerService. Plugins SHOULD provide this capability.
-      // In rare cases certain plugins may wish to omit the
+      // In rare cases certain plugins MAY wish to omit the
       // ControllerService entirely from their implementation, but such
       // SHOULD NOT be the common case.
       // The presence of this capability determines whether the CO will
@@ -127,7 +127,7 @@ message PluginCapability {
       CONTROLLER_SERVICE = 1;
 
       // VOLUME_ACCESSIBILITY_CONSTRAINTS indicates that the volumes for
-      // this plugin may not be equally accessible by all nodes in the
+      // this plugin MAY NOT be equally accessible by all nodes in the
       // cluster. The CO MUST use the topology information returned by
       // CreateVolumeRequest along with the topology information
       // returned by NodeGetInfo to ensure that a given volume is
@@ -173,7 +173,7 @@ message CreateVolumeRequest {
   // The suggested name for the storage space. This field is REQUIRED.
   // It serves two purposes:
   // 1) Idempotency - This name is generated by the CO to achieve
-  //    idempotency.  The Plugin should ensure that multiple
+  //    idempotency.  The Plugin SHOULD ensure that multiple
   //    `CreateVolume` calls for the same name do not result in more
   //    than one piece of storage provisioned corresponding to that
   //    name. If a Plugin is unable to enforce idempotency, the CO's
@@ -202,7 +202,7 @@ message CreateVolumeRequest {
   // requirement of the volume to be provisioned. If not specified, the
   // Plugin MAY choose an implementation-defined capacity range. If
   // specified it MUST always be honored, even when creating volumes
-  // from a source; which may force some backends to internally extend
+  // from a source; which MAY force some backends to internally extend
   // the volume after creating it.
   CapacityRange capacity_range = 2;
 
@@ -384,7 +384,7 @@ message Volume {
   // The contents of this field SHOULD NOT contain sensitive
   // information.
   // The contents of this field SHOULD NOT be used for uniquely
-  // identifying a volume. The `volume_id` alone should be sufficient to
+  // identifying a volume. The `volume_id` alone SHOULD be sufficient to
   // identify the volume.
   // A volume uniquely identified by `volume_id` SHALL always report the
   // same volume_context.
@@ -408,7 +408,7 @@ message Volume {
   // from a given node when scheduling workloads.
   // This field is OPTIONAL. If it is not specified, the CO MAY assume
   // the volume is equally accessible from all nodes in the cluster and
-  // may schedule workloads referencing the volume on any available
+  // MAY schedule workloads referencing the volume on any available
   // node.
   //
   // Example 1:
@@ -562,9 +562,9 @@ message TopologyRequirement {
 // A topological segment is a specific instance of a topological domain,
 // like "zone3", "rack3", etc.
 // For example {"com.company/zone": "Z1", "com.company/rack": "R3"}
-// Valid keys have two segments: an optional prefix and name, separated
+// Valid keys have two segments: an OPTIONAL prefix and name, separated
 // by a slash (/), for example: "com.company.example/zone".
-// The key name segment is required. The prefix is optional.
+// The key name segment is REQUIRED. The prefix is OPTIONAL.
 // The key name MUST be 63 characters or less, begin and end with an
 // alphanumeric character ([a-z0-9A-Z]), and contain only dashes (-),
 // underscores (_), dots (.), or alphanumerics in between, for example
@@ -644,7 +644,7 @@ message ControllerPublishVolumeResponse {
   // The contents of this field SHOULD NOT contain sensitive
   // information.
   // The contents of this field SHOULD NOT be used for uniquely
-  // identifying a volume. The `id` alone should be sufficient to
+  // identifying a volume. The `volume_id` alone SHOULD be sufficient to
   // identify the volume.
   // This field is OPTIONAL and when present MUST be passed to
   // subsequent `NodeStageVolume` or `NodePublishVolume` calls
@@ -817,9 +817,9 @@ message ControllerServiceCapability {
       CREATE_DELETE_SNAPSHOT = 5;
       LIST_SNAPSHOTS = 6;
       // Plugins supporting volume cloning at the storage level MAY
-      // report this capability. The source volume must be managed by
+      // report this capability. The source volume MUST be managed by
       // the same plugin. Not all volume sources and parameters
-      // combinations may work.
+      // combinations MAY work.
       CLONE_VOLUME = 7;
       // Indicates the SP supports ControllerPublishVolume.readonly
       // field.
@@ -900,7 +900,7 @@ message Snapshot {
   string source_volume_id = 3;
 
   // Timestamp when the point-in-time snapshot is taken on the storage
-  // system. The format of this field should be a Unix nanoseconds time
+  // system. The format of this field SHOULD be a Unix nanoseconds time
   // encoded as an int64. On Unix, the command `date +%s%N` returns the
   // current time in nanoseconds since 1970-01-01 00:00:00 UTC. This
   // field is REQUIRED.