From 007da664eac96ba7ff06a2c787e66410a4c6a028 Mon Sep 17 00:00:00 2001 From: Christian Schwarz Date: Thu, 5 Oct 2017 21:56:37 +0200 Subject: [PATCH] README: document naming inconsitency with datasets & filesystems --- README.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/README.md b/README.md index 94625f3..22454bd 100644 --- a/README.md +++ b/README.md @@ -52,3 +52,20 @@ Make sure to develop an understanding how zrepl is typically used by studying th * Open an issue when starting to hack on a new feature * Commits should reference the issue they are related to * Docs improvements not documenting new features do not require an issue. + +### Glossary & Naming Inconsistencies + +In ZFS, *dataset* refers to the objects *filesystem*, *ZVOL* and *snapshot*.
+However, we need a word for *filesystem* & *ZVOL* but not a snapshot, bookmark, etc. + +Toward the user, the following terminology is used: + +* **filesystem**: a ZFS filesystem or a ZVOL +* **filesystem version**: a ZFS snapshot or a bookmark + +Sadly, the zrepl implementation is inconsistent in its use of these words: +variables and types are often named *dataset* when they in fact refer to a *filesystem*. + +There will not be a big refactoring (an attempt was made, but it's destroying too much history without much gain). + +However, new contributions & patches should fix naming without further notice in the commit message.