Merge pull request #231 from ribasushi/explicit-warning-unexpected-mode-bits

Be more explicit about future changes to `mode`

Author: Stebalien

UNIXFS.md

@@ -82,10 +82,14 @@ For files comprised of a single block, the 'Type' field will be set to 'File', '
 UnixFS currently supports two optional metadata fields:
 
 * `mode` -- The `mode` is for persisting the file permissions in [numeric notation](https://en.wikipedia.org/wiki/File_system_permissions#Numeric_notation) \[[spec](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_stat.h.html)\].
-  If unspecified this defaults to `0755` for directories/HAMT shards and `0644` for all other types where applicable
-  The nine least significant bits represent  `ugo-rwx`
-  The next three least significant bits represent `setuid`, `setgid` and the `sticky bit`
-  All others are reserved for future use
+  - If unspecified this defaults to
+    - `0755` for directories/HAMT shards
+    - `0644` for all other types where applicable
+  - The nine least significant bits represent  `ugo-rwx`
+  - The next three least significant bits represent `setuid`, `setgid` and the `sticky bit`
+  - The remaining 20 bits are reserved for future use, and are subject to change. Spec implementations **MUST** handle bits they do not expect as follows:
+    - For future-proofing the (de)serialization layer must preserve the entire uint32 value during clone/copy operations, modifying only bit values that have a well defined meaning: `clonedValue = ( modifiedBits & 07777 ) | ( originalValue & 0xFFFFF000 )`
+    - Implementations of this spec must proactively mask off bits without a defined meaning in the implemented version of the spec: `interpretedValue = originalValue & 07777`
 * `mtime` -- The modification time in seconds since the epoch. This defaults to the unix epoch if unspecified
 
 ### Deduplication and inlining