Merge pull request #6955 from Iceber/update_metadata_schema_comment

fix comments on metadata schema and update namespace doc

docs/namespaces.md

@@ -24,6 +24,8 @@ ns, ok := namespaces.Namespace(ctx)
 
 Because the client calls containerd's gRPC API to interact with the daemon, all API calls require a context with a namespace set.
 
+> Note that a namespace cannot be named `"version"` ([#6944](https://github.com/containerd/containerd/issues/6944)).
+
 ## How low level is the implementation?
 
 Namespaces are passed through the containerd API to the underlying plugins providing functionality.

metadata/buckets.go

@@ -44,10 +44,15 @@
 //
 // Below is the current database schema. This should be updated each time
 // the structure is changed in addition to adding a migration and incrementing
-// the database version. Note that `╘══*...*` refers to maps with arbitrary
+// the database version.
-// keys.
+// Notes:
-//  ├──version : <varint>                        - Latest version, see migrations
+//  * `╘══*...*` refers to maps with arbitrary keys
+//  * `version` is a key to a numeric value identifying the minor revisions
+//    of schema version
+//  * a namespace in a schema bucket cannot be named "version"
+//
 //  └──v1                                        - Schema version bucket
+//     ├──version : <varint>                     - Latest version, see migrations
 //     ╘══*namespace*
 //        ├──labels
 //        │  ╘══*key* : <string>                 - Label value