btrfs-progs: balance: add extra delay if converting with a missing de…

Documentation/btrfs-scrub.rst

@@ -89,6 +89,11 @@ start [-BdrRf] <path>|<device>
         -r
                 run in read-only mode, do not attempt to correct anything, can
                 be run on a read-only filesystem
+
+                Note that a read-only scrub on a read-write filesystem can
+                still cause writes into the filesystem due to some internal
+                limitations.  Only a read-only scrub on a read-only filesystem
+                can avoid writes from scrub.
         -R
                 raw print mode, print full data instead of summary
         -f

Documentation/ch-scrub-intro.rst

@@ -46,6 +46,16 @@ read-write mounted filesystem.
    used, with expert guidance, to rebuild certain corrupted filesystem structures
    in the absence of any good replica.
 
+.. note::
+   Read-only scrub on a read-write filesystem will cause some writes into the
+   filesystem.
+
+   This is due to the design limitation to prevent race between marking block
+   group read-only and writing back block group items.
+
+   To avoid any writes from scrub, one has to run read-only scrub on read-only
+   filesystem.
+
 The user is supposed to run it manually or via a periodic system service. The
 recommended period is a month but it could be less. The estimated device bandwidth
 utilization is about 80% on an idle filesystem.

Documentation/dev/CmdLineConventions.rst

@@ -0,0 +1,148 @@
+Command line, formatting, UI guidelines
+=======================================
+
+The guidelines try to follow common principles and build on experience based on
+user feedback or practices seen in other projects. There are no strict rules
+but rather vague statements or principles that is recommended to follow.
+It's recommended to follow them or use them as review checklist. Optimize for
+humans.
+
+- *sane defaults*
+- *principle of least surprise*
+- *it does what it says*
+- *it says what it does*
+- *frequently performed actions have shortcuts*
+- *easy thing easy, hard things possible*
+- *dangerous actions are explicit or need a confirmation*
+- *same name means the same thing everywhere*
+- *it's hard to change things once they are released*
+
+Command line options
+--------------------
+
+Unless there's a precedent for using a well known short option name, using
+long option for first implementation is always safe.
+
+All options parsers use :manref:`getopt(3)`, the behaviour is known and
+consistent with most tools and utilities found elsewhere. Options and parameters
+are sorted (options first) up to the ``--`` delimiter. Global options follow right
+after the main command and are parsed separately from the subcommand, :command:`btrfs`,
+following syntax
+:command:`btrfs [global options] subcommand [options] <parameters...>`.
+
+Short options
+^^^^^^^^^^^^^
+
+Short options are in short supply, ``a-z`` and ``A-Z``.
+
+*  reserved for the most common operations
+*  should follow some common scheme
+
+   * verbose (-v), recursive (-r, -R), force (-f), output redirection (-o), ...
+   * same option means the same thing in a group of related options
+   * mnemonic naming when possible, e.g. first letter of the action like
+     *-l* for *length* but with growing number of features clashes can and will
+     happen
+
+*  *upper case* could mean negating or extending meaning of lower case if it
+   exists, using both upper and lower case for different purposes can be
+   confusing
+*  most short options should have an equivalent long option
+*  rarely done actions do not need short options at all
+
+Long options
+^^^^^^^^^^^^
+
+Long options are meant to be descriptive, e.g. when used in scripts, documentation
+or change descriptions.
+
+*  brief but descriptive
+*  long and descriptive can be used in justified cases (e.g. conversion options
+   in :doc:`btrfstune` because of the single command without subcommands)
+
+Option parameters
+^^^^^^^^^^^^^^^^^
+
+.. note::
+   **Avoid using optional parameter.** This is a usability misfeature of
+   *getopt()* because of the mandatory short option syntax where the parameter
+   *must* be glued to the option name, like *-czstd* so this looks like a group
+   of short options but it is not. In this example *-c zstd* is not the same,
+   the parameter will take default value and *zstd* will be understood as
+   another parameter. Unfortunate examples are :command:`btrfs filesystem
+   defrag -c` and :command:`btrfs balance start -d`. Both quite common and we
+   probably cannot fix this without breaking existing scripts.
+
+Help text
+^^^^^^^^^
+
+Description in the help text should be long enough to describe what it does, mention default
+value and should not be too long or detailed. Referring to documentation is recommended
+when it's really wise to read it first before using it. Otherwise it's a reminder
+to user who has probably used it in the past.
+
+*  short help for *--help* output: :command:`btrfs subcommand [options] param1 param2`
+
+   * the number of options gets unwieldy for a command with many tunable features
+     so it's better to write a short description and document properly everything
+     in the manual page or in the followup text
+
+*  short description after command line: terse but understandable explanation
+   what the command does, mention dangers
+
+*  long description after the short description
+
+   *  explain in more detail what the command does, different use cases, things to notice
+   *  more complex things should be documented in the manual pages and pointed to
+      (examples)
+
+Command output, verbosity
+-------------------------
+
+Structured output
+^^^^^^^^^^^^^^^^^
+
+If the output consists of a lot of information, try to present it in a concise
+way and structure related information together using some known formats
+or already used ones in this project.
+
+* `Key: value`, spacing by tabs or spaces
+* use indentation and empty lines for visual separation
+* value column alignment for quick skimming
+* must be parseable and also visually comprehensible, related information
+  on one line usually satisfies both (*greppable*)
+
+Default output
+^^^^^^^^^^^^^^
+
+* UNIX commands do one thing and say nothing, we diverge from that as it does
+  not work well for a multi-command tools
+* default output is one line shortly describing the action
+
+  * why: running commands from scripts or among many other commands should be
+    noticeable due to progress tracking or for analysis if something goes wrong
+  * there's a global option to make the commands silent :command:`btrfs -q subcommand`,
+    this can be easily scripted e.g. storing the global verbosity option in a
+    variable, :command:`btrfs $quiet subcommand` and then enabling or disabling as needed
+
+* there should be a line length limit so the output visually fits to one line without
+  wrapping, there's no exact number of columns, assume something around 100,
+  keep related information on one line (printed) rather then breaking it.
+
+Formatting
+^^^^^^^^^^
+
+* numeric values are not quoted
+* string values are quoted if they would be confused when parsed word by word
+  (e.g. file paths)
+  * quoting is by single apostrophe on both ends, no fancy backtick+quote
+* all messages follow a few known and understood schemes
+
+Verbosity levels
+^^^^^^^^^^^^^^^^
+
+* 0 - quiet, only errors to *stderr*, nothing to *stdout*
+* 1 - default, one line, see above
+* 2 - inform about main steps that happen
+* 3 - a little bit more detailed about what happens during level 2
+* 4 - possibly lots of information, for debugging and close inspection what happens

Documentation/dev/Development-notes.rst

@@ -413,6 +413,7 @@ Please refer to the option documentation for further details.
 
    -  **CONFIG_BTRFS_DEBUG**
    -  **CONFIG_BTRFS_ASSERT**
+   -  **CONFIG_BTRFS_EXPERIMENTAL**
    -  **CONFIG_BTRFS_FS_RUN_SANITY_TESTS** -- basic tests on module load
    -  **CONFIG_BTRFS_FS_CHECK_INTEGRITY** -- block integrity checker
       enabled by mount options

Documentation/index.rst

@@ -84,6 +84,7 @@ is in the :doc:`manual pages<man-index>`.
    dev/dev-internal-apis
    dev/ReleaseChecklist
    dev/GithubReviewWorkflow
+   dev/CmdLineConventions
    btrfs-ioctl
 
 

Documentation/mkfs.btrfs.rst

@@ -155,6 +155,19 @@ OPTIONS
                 contain the files from *rootdir*. Since version 4.14.1 the filesystem size is
                 not minimized. Please see option *--shrink* if you need that functionality.
 
+--compress <algo>[:<level>]
+        Try to compress files when using *--rootdir*.  Supported values for *algo* are
+        *no* (the default), *zstd*, *lzo* or *zlib*.  The optional value *level* is a
+        compression level, 1..15 for *zstd*, 1..9 for *zlib*.
+
+        As with the kernel, :command:`mkfs.btrfs` won't write compressed extents when
+        they would be larger than the uncompressed versions, and will set file attribute
+        *NOCOMPRESS* if its beginning is found to be incompressible.
+
+        .. note::
+                The support for ZSTD and LZO is a compile-time option, please check
+                the output of :command:`mkfs.btrfs --help` for the actual support.
+
 -u|--subvol <type>:<subdir>
         Specify that *subdir* is to be created as a subvolume rather than a regular
         directory.  The option *--rootdir* must also be specified, and *subdir* must be an
@@ -212,15 +225,6 @@ OPTIONS
 
                 $ mkfs.btrfs -O list-all
 
---compress <algo>[:<level>]
-        Try to compress files when using *--rootdir*.  Supported values for *algo* are
-        *no* (the default), *zlib*, *lzo*, and *zstd*.  The optional value *level* is a
-        compression level, from 1 to 9 for ZLIB and from 1 to 15 for ZSTD.
-
-        As with the kernel, :command:`mkfs.btrfs` won't write compressed extents when
-        they would be larger than the uncompressed versions, and will mark a file as
-        `nocompress` if its beginning is found to be incompressible.
-
 -f|--force
         Forcibly overwrite the block devices when an existing filesystem is detected.
         By default, :command:`mkfs.btrfs` will utilize *libblkid* to check for any known
@@ -389,7 +393,7 @@ block-group-tree
 .. _mkfs-feature-raid-stripe-tree:
 
 raid-stripe-tree
-        (kernel support since 6.7, CONFIG_BTRFS_DEBUG)
+        (kernel support since 6.7, CONFIG_BTRFS_DEBUG/CONFIG_BTRFS_EXPERIMENTAL)
 
         Separate tree for logical file extent mapping where the physical mapping
         may not match on multiple devices. This is now used in zoned mode to
@@ -400,8 +404,9 @@ raid-stripe-tree
 
         .. note::
                 Due to the status of implementation it is enabled only in
-                builds with CONFIG_BTRFS_DEBUG. Support by the kernel module
-                can be found in the sysfs feature list.
+                builds with CONFIG_BTRFS_DEBUG/CONFIG_BTRFS_EXPERIMENTAL.
+                Support by the kernel module can be found in the sysfs feature
+                list.
 
 squota
 	(kernel support since 6.7)