steveloughran commented on code in PR #6198:
URL: https://github.com/apache/hadoop/pull/6198#discussion_r1381581642
##########
hadoop-common-project/hadoop-common/src/site/markdown/filesystem/filesystem.md:
##########
@@ -601,7 +601,32 @@ on the filesystem.
1. The outcome of this operation MUST be identical to the value of
`getFileStatus(P).getBlockSize()`.
-1. By inference, it MUST be > 0 for any file of length > 0.
+2. By inference, it MUST be > 0 for any file of length > 0.
+
+### `Path getEnclosingRoot(Path p)`
+
+This method is used to find a root directory for a path given. This is useful
for creating
+staging and temp directories in the same enclosing root directory. There are
constraints around how
+renames are allowed to atomically occur (ex. across hdfs volumes or across
encryption zones).
+
+For any two paths p1 and p2 that do not have the same enclosing root,
`rename(p1, p2)` is expected to fail or will not
+be atomic.
+
+The following statement is always true:
+`getEnclosingRoot(p) == getEnclosingRoot(getEnclosingRoot(p))`
+
+#### Preconditions
+
+The path does not have to exist, but the path does need to be valid and
reconcilable by the filesystem
+* if a linkfallback is used all paths are reconcilable
+* if a linkfallback is not used there must be a mount point covering the path
+
+
+#### Postconditions
+
+* The path returned will not be null, if there is no deeper enclosing root,
the root path ("/") will be returned.
+* The path returned is a directory
Review Comment:
the python is trying to define the rules, the english is a wrapper around
it. So think about how you'd convert those bullet points in terms of assertions
you'd have before and after an implementation
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: common-issues-unsubscr...@hadoop.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: common-issues-unsubscr...@hadoop.apache.org
For additional commands, e-mail: common-issues-h...@hadoop.apache.org
