[PATCH 1/2] btrfs-progs: Add device management related paragraph.

[PATCH 1/2] btrfs-progs: Add device management related paragraph.

[Qu Wenruo]

Add device management related paragraph to better explain btrfs device
management.

Cc: Marc MERLIN <marc@merlins.org>
Signed-off-by: Qu Wenruo <quwenruo@cn.fujitsu.com>
---
 Documentation/btrfs-balance.txt |  3 +++
 Documentation/btrfs-device.txt  | 42 +++++++++++++++++++++++++++++++++++++++++
 Documentation/btrfs-replace.txt |  4 ++++
 3 files changed, 49 insertions(+)

diff --git a/Documentation/btrfs-balance.txt b/Documentation/btrfs-balance.txt
index 2289fdf..1b1861c 100644
--- a/Documentation/btrfs-balance.txt
+++ b/Documentation/btrfs-balance.txt
@@ -14,6 +14,8 @@ DESCRIPTION
 'btrfs balance' is used to balance chunks in a btrfs filesystem across
 multiple or even single device.
 
+See `btrfs-device`(8) for more details about the effect on device management.
+
 SUBCOMMAND
 ----------
 <path>::
@@ -75,3 +77,4 @@ further details.
 SEE ALSO
 --------
 `mkfs.btrfs`(8),
+`btrfs-device`(8)
diff --git a/Documentation/btrfs-device.txt b/Documentation/btrfs-device.txt
index 20d7bcd..474d411 100644
--- a/Documentation/btrfs-device.txt
+++ b/Documentation/btrfs-device.txt
@@ -14,6 +14,46 @@ DESCRIPTION
 'btrfs device' is used to control the btrfs devices, since btrfs can be used
 across several devices, 'btrfs device' is used for multiple device management.
 
+DEVICE MANAGEMENT
+-----------------
+Btrfs filesystem is capable to manage multiple devices.
+
+Btrfs filesystem use different profiles to manage different RAID level, and
+use balance to rebuild chunks, also devices can be added/removed/replace
+online.
+
+Profile::
+Btrfs filesystem use data/metadata profiles to manage allocation/duplication
+mechanism. Profiles like RAID level can be assigned to data and metadata separately.
++
+See `mkfs.btrfs`(8) for more details.
+
+RAID level::
+Btrfs filesystem supports most of the standard RAID level: 0/1/5/6/10.
+RAID levels can be assigned at mkfs time or online.
++
+See `mkfs.btrfs`(8) for mkfs time RAID level assign and `btrfs-balance`(8) for
+online RAID level assign.
+
+Balance::
+`btrfs-balance`(8) subcommand can be used to balance or rebuild chunks to the
+desired profile.
++
+Due to the fact that balance can rebuild/recovery chunks according to its RAID
+duplication if possible, so when using RAID1/5/6/10 with some devices failed
+and you just added a new device to btrfs using `btrfs-device`(8), you should
+run `btrfs-balance`(8) to rebuild the chunks.
++
+See `btrfs-balance`(8) for more details.
+
+Device add/remove/replace::
+Device can be added/removed using `btrfs-replace`(8) subcommand and replaced
+using `btrfs-replace`(8).
++
+When device is removed or replaced, btrfs will do the chunk rebuild if needed.
++
+See `btrfs-replace`(8) and this man page for more details.
+
 SUBCOMMAND
 ----------
 'add' [-Kf] <dev> [<dev>...] <path>::
@@ -73,3 +113,5 @@ further details.
 SEE ALSO
 --------
 `mkfs.btrfs`(8),
+`btrfs-replace`(8),
+`btrfs-balance`(8)
diff --git a/Documentation/btrfs-replace.txt b/Documentation/btrfs-replace.txt
index 8c5dcc4..15a46c2 100644
--- a/Documentation/btrfs-replace.txt
+++ b/Documentation/btrfs-replace.txt
@@ -13,6 +13,9 @@ DESCRIPTION
 -----------
 'btrfs replace' is used to replace btrfs managed devices with other device.
 
+It is recommended to see `btrfs-device`(8) for more details about btrfs device
+management.
+
 SUBCOMMAND
 ----------
 'start' [-Bfr] <srcdev>|<devid> <targetdev> <path>::
@@ -74,3 +77,4 @@ further details.
 SEE ALSO
 --------
 `mkfs.btrfs`(8),
+`btrfs-device`(8),
-- 
1.9.2

[PATCH 2/2] btrfs-progs: Add explain on btrfs-zero-log.

[Qu Wenruo]

Add more explain on btrfs-zero-log about when to use it.

Cc: Marc MERLIN <marc@merlins.org>
Signed-off-by: Qu Wenruo <quwenruo@cn.fujitsu.com>
---
 Documentation/btrfs-zero-log.txt | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/Documentation/btrfs-zero-log.txt b/Documentation/btrfs-zero-log.txt
index e3041fa..a8e4dd3 100644
--- a/Documentation/btrfs-zero-log.txt
+++ b/Documentation/btrfs-zero-log.txt
@@ -17,6 +17,24 @@ allow you to mount the filesystem again.
 The common case where this happens has been fixed a long time ago,
 so it is unlikely that you will see this particular problem.
 
+One can determine whether 'btrfs-zero-log' is needed according to the kernel
+backtrace:
+----
+? replay_one_dir_item+0xb5/0xb5 [btrfs]
+? walk_log_tree+0x9c/0x19d [btrfs]
+? btrfs_read_fs_root_no_radix+0x169/0x1a1 [btrfs]
+? btrfs_recover_log_trees+0x195/0x29c [btrfs]
+? replay_one_dir_item+0xb5/0xb5 [btrfs]
+? btree_read_extent_buffer_pages+0x76/0xbc [btrfs]
+? open_ctree+0xff6/0x132c [btrfs]
+----
+
+If the errors are like above, then 'btrfs-zero-log' should be used to clear
+the log and the filesystem may be mounted normally again.
+
+NOTE: If you use btrfs as the root filesystem, you may want to include
+'btrfs-zero-log' into initramdisk if the log problems hits you often.
+
 EXIT STATUS
 -----------
 'btrfs-zero-log' will return 0 if no error happened.
-- 
1.9.2

Re: [PATCH 2/2] btrfs-progs: Add explain on btrfs-zero-log.

[Marc MERLIN]

On Fri, Apr 11, 2014 at 10:43:53AM +0800, Qu Wenruo wrote:
> Add more explain on btrfs-zero-log about when to use it.
> 
> Cc: Marc MERLIN <marc@merlins.org>
> Signed-off-by: Qu Wenruo <quwenruo@cn.fujitsu.com>

Reviewed-by: Marc MERLIN <marc@merlins.org>

Looks good, thank you.

Marc

> ---
>  Documentation/btrfs-zero-log.txt | 18 ++++++++++++++++++
>  1 file changed, 18 insertions(+)
> 
> diff --git a/Documentation/btrfs-zero-log.txt b/Documentation/btrfs-zero-log.txt
> index e3041fa..a8e4dd3 100644
> --- a/Documentation/btrfs-zero-log.txt
> +++ b/Documentation/btrfs-zero-log.txt
> @@ -17,6 +17,24 @@ allow you to mount the filesystem again.
>  The common case where this happens has been fixed a long time ago,
>  so it is unlikely that you will see this particular problem.
>  
> +One can determine whether 'btrfs-zero-log' is needed according to the kernel
> +backtrace:
> +----
> +? replay_one_dir_item+0xb5/0xb5 [btrfs]
> +? walk_log_tree+0x9c/0x19d [btrfs]
> +? btrfs_read_fs_root_no_radix+0x169/0x1a1 [btrfs]
> +? btrfs_recover_log_trees+0x195/0x29c [btrfs]
> +? replay_one_dir_item+0xb5/0xb5 [btrfs]
> +? btree_read_extent_buffer_pages+0x76/0xbc [btrfs]
> +? open_ctree+0xff6/0x132c [btrfs]
> +----
> +
> +If the errors are like above, then 'btrfs-zero-log' should be used to clear
> +the log and the filesystem may be mounted normally again.
> +
> +NOTE: If you use btrfs as the root filesystem, you may want to include
> +'btrfs-zero-log' into initramdisk if the log problems hits you often.
> +
>  EXIT STATUS
>  -----------
>  'btrfs-zero-log' will return 0 if no error happened.
> -- 
> 1.9.2
> 
> --
> To unsubscribe from this list: send the line "unsubscribe linux-btrfs" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 

-- 
"A mouse is a device used to point at the xterm you want to type in" - A.S.R.
Microsoft is to operating systems ....
                                      .... what McDonalds is to gourmet cooking
Home page: http://marc.merlins.org/  

Re: [PATCH 1/2] btrfs-progs: Add device management related paragraph.

[Marc MERLIN]

On Fri, Apr 11, 2014 at 10:43:52AM +0800, Qu Wenruo wrote:
> Add device management related paragraph to better explain btrfs device
> management.

Thank you for these updates.
 
> Cc: Marc MERLIN <marc@merlins.org>
> Signed-off-by: Qu Wenruo <quwenruo@cn.fujitsu.com>

(comments below)

> ---
>  Documentation/btrfs-balance.txt |  3 +++
>  Documentation/btrfs-device.txt  | 42 +++++++++++++++++++++++++++++++++++++++++
>  Documentation/btrfs-replace.txt |  4 ++++
>  3 files changed, 49 insertions(+)
> 
> diff --git a/Documentation/btrfs-balance.txt b/Documentation/btrfs-balance.txt
> index 2289fdf..1b1861c 100644
> --- a/Documentation/btrfs-balance.txt
> +++ b/Documentation/btrfs-balance.txt
> @@ -14,6 +14,8 @@ DESCRIPTION
>  'btrfs balance' is used to balance chunks in a btrfs filesystem across
>  multiple or even single device.
>  
> +See `btrfs-device`(8) for more details about the effect on device management.
> +
>  SUBCOMMAND
>  ----------
>  <path>::
> @@ -75,3 +77,4 @@ further details.
>  SEE ALSO
>  --------
>  `mkfs.btrfs`(8),
> +`btrfs-device`(8)
> diff --git a/Documentation/btrfs-device.txt b/Documentation/btrfs-device.txt
> index 20d7bcd..474d411 100644
> --- a/Documentation/btrfs-device.txt
> +++ b/Documentation/btrfs-device.txt
> @@ -14,6 +14,46 @@ DESCRIPTION
>  'btrfs device' is used to control the btrfs devices, since btrfs can be used
>  across several devices, 'btrfs device' is used for multiple device management.
>  
> +DEVICE MANAGEMENT
> +-----------------
> +Btrfs filesystem is capable to manage multiple devices.
> +
> +Btrfs filesystem use different profiles to manage different RAID level, and
> +use balance to rebuild chunks, also devices can be added/removed/replace
> +online.
> +
> +Profile::
> +Btrfs filesystem use data/metadata profiles to manage allocation/duplication
> +mechanism. Profiles like RAID level can be assigned to data and metadata separately.
> ++
> +See `mkfs.btrfs`(8) for more details.
> +
> +RAID level::
> +Btrfs filesystem supports most of the standard RAID level: 0/1/5/6/10.
> +RAID levels can be assigned at mkfs time or online.
> ++
> +See `mkfs.btrfs`(8) for mkfs time RAID level assign and `btrfs-balance`(8) for
> +online RAID level assign.
> +
> +Balance::
> +`btrfs-balance`(8) subcommand can be used to balance or rebuild chunks to the
> +desired profile.
> ++
> +Due to the fact that balance can rebuild/recovery chunks according to its RAID
> +duplication if possible, so when using RAID1/5/6/10 with some devices failed
> +and you just added a new device to btrfs using `btrfs-device`(8), you should
> +run `btrfs-balance`(8) to rebuild the chunks.
> ++
> +See `btrfs-balance`(8) for more details.
> +
> +Device add/remove/replace::
> +Device can be added/removed using `btrfs-replace`(8) subcommand and replaced
> +using `btrfs-replace`(8).

I'm not sure I understand this sentence exactly.

> +When device is removed or replaced, btrfs will do the chunk rebuild if needed.
> ++
> +See `btrfs-replace`(8) and this man page for more details.
> +
>  SUBCOMMAND
>  ----------
>  'add' [-Kf] <dev> [<dev>...] <path>::
> @@ -73,3 +113,5 @@ further details.
>  SEE ALSO
>  --------
>  `mkfs.btrfs`(8),
> +`btrfs-replace`(8),
> +`btrfs-balance`(8)
> diff --git a/Documentation/btrfs-replace.txt b/Documentation/btrfs-replace.txt
> index 8c5dcc4..15a46c2 100644
> --- a/Documentation/btrfs-replace.txt
> +++ b/Documentation/btrfs-replace.txt
> @@ -13,6 +13,9 @@ DESCRIPTION
>  -----------
>  'btrfs replace' is used to replace btrfs managed devices with other device.

I would add a quick line here saying that it's not currently supported for
RAID5/6, and to see btrfs-device for add/delete to get around the replace
missing problem.

I've explained that in more details on
https://btrfs.wiki.kernel.org/index.php/FAQ#Can_I_use_RAID.5B56.5D_on_my_Btrfs_filesystem.3F
but it may not be a great page to link to.
Ok, I just made a new nice page for you:
https://btrfs.wiki.kernel.org/index.php/RAID56

Do you think it would be ok to link to
https://btrfs.wiki.kernel.org/index.php/RAID56#Parity_Rebuilds_and_Advanced_Disk_Replacement
in the btrfs replace man page?
  
> +It is recommended to see `btrfs-device`(8) for more details about btrfs device
> +management.
> +
>  SUBCOMMAND
>  ----------
>  'start' [-Bfr] <srcdev>|<devid> <targetdev> <path>::
> @@ -74,3 +77,4 @@ further details.
>  SEE ALSO
>  --------
>  `mkfs.btrfs`(8),
> +`btrfs-device`(8),
> -- 
> 1.9.2

The rest looks good.

Thank you,
Marc
-- 
"A mouse is a device used to point at the xterm you want to type in" - A.S.R.
Microsoft is to operating systems ....
                                      .... what McDonalds is to gourmet cooking
Home page: http://marc.merlins.org/  

Re: [PATCH 1/2] btrfs-progs: Add device management related paragraph.

[Qu Wenruo]

-------- Original Message --------
Subject: Re: [PATCH 1/2] btrfs-progs: Add device management related 
paragraph.
From: Marc MERLIN <marc@merlins.org>
To: Qu Wenruo <quwenruo@cn.fujitsu.com>
Date: 2014年04月11日 14:10
> On Fri, Apr 11, 2014 at 10:43:52AM +0800, Qu Wenruo wrote:
>> Add device management related paragraph to better explain btrfs device
>> management.
> Thank you for these updates.
>   
>> Cc: Marc MERLIN <marc@merlins.org>
>> Signed-off-by: Qu Wenruo <quwenruo@cn.fujitsu.com>
> (comments below)
>
>> ---
>>   Documentation/btrfs-balance.txt |  3 +++
>>   Documentation/btrfs-device.txt  | 42 +++++++++++++++++++++++++++++++++++++++++
>>   Documentation/btrfs-replace.txt |  4 ++++
>>   3 files changed, 49 insertions(+)
>>
>> diff --git a/Documentation/btrfs-balance.txt b/Documentation/btrfs-balance.txt
>> index 2289fdf..1b1861c 100644
>> --- a/Documentation/btrfs-balance.txt
>> +++ b/Documentation/btrfs-balance.txt
>> @@ -14,6 +14,8 @@ DESCRIPTION
>>   'btrfs balance' is used to balance chunks in a btrfs filesystem across
>>   multiple or even single device.
>>   
>> +See `btrfs-device`(8) for more details about the effect on device management.
>> +
>>   SUBCOMMAND
>>   ----------
>>   <path>::
>> @@ -75,3 +77,4 @@ further details.
>>   SEE ALSO
>>   --------
>>   `mkfs.btrfs`(8),
>> +`btrfs-device`(8)
>> diff --git a/Documentation/btrfs-device.txt b/Documentation/btrfs-device.txt
>> index 20d7bcd..474d411 100644
>> --- a/Documentation/btrfs-device.txt
>> +++ b/Documentation/btrfs-device.txt
>> @@ -14,6 +14,46 @@ DESCRIPTION
>>   'btrfs device' is used to control the btrfs devices, since btrfs can be used
>>   across several devices, 'btrfs device' is used for multiple device management.
>>   
>> +DEVICE MANAGEMENT
>> +-----------------
>> +Btrfs filesystem is capable to manage multiple devices.
>> +
>> +Btrfs filesystem use different profiles to manage different RAID level, and
>> +use balance to rebuild chunks, also devices can be added/removed/replace
>> +online.
>> +
>> +Profile::
>> +Btrfs filesystem use data/metadata profiles to manage allocation/duplication
>> +mechanism. Profiles like RAID level can be assigned to data and metadata separately.
>> ++
>> +See `mkfs.btrfs`(8) for more details.
>> +
>> +RAID level::
>> +Btrfs filesystem supports most of the standard RAID level: 0/1/5/6/10.
>> +RAID levels can be assigned at mkfs time or online.
>> ++
>> +See `mkfs.btrfs`(8) for mkfs time RAID level assign and `btrfs-balance`(8) for
>> +online RAID level assign.
>> +
>> +Balance::
>> +`btrfs-balance`(8) subcommand can be used to balance or rebuild chunks to the
>> +desired profile.
>> ++
>> +Due to the fact that balance can rebuild/recovery chunks according to its RAID
>> +duplication if possible, so when using RAID1/5/6/10 with some devices failed
>> +and you just added a new device to btrfs using `btrfs-device`(8), you should
>> +run `btrfs-balance`(8) to rebuild the chunks.
>> ++
>> +See `btrfs-balance`(8) for more details.
>> +
>> +Device add/remove/replace::
>> +Device can be added/removed using `btrfs-replace`(8) subcommand and replaced
>> +using `btrfs-replace`(8).
> I'm not sure I understand this sentence exactly.
Sorry for my poor English, I'll try to change it to a better expression.
>
>> +When device is removed or replaced, btrfs will do the chunk rebuild if needed.
>> ++
>> +See `btrfs-replace`(8) and this man page for more details.
>> +
>>   SUBCOMMAND
>>   ----------
>>   'add' [-Kf] <dev> [<dev>...] <path>::
>> @@ -73,3 +113,5 @@ further details.
>>   SEE ALSO
>>   --------
>>   `mkfs.btrfs`(8),
>> +`btrfs-replace`(8),
>> +`btrfs-balance`(8)
>> diff --git a/Documentation/btrfs-replace.txt b/Documentation/btrfs-replace.txt
>> index 8c5dcc4..15a46c2 100644
>> --- a/Documentation/btrfs-replace.txt
>> +++ b/Documentation/btrfs-replace.txt
>> @@ -13,6 +13,9 @@ DESCRIPTION
>>   -----------
>>   'btrfs replace' is used to replace btrfs managed devices with other device.
> I would add a quick line here saying that it's not currently supported for
> RAID5/6, and to see btrfs-device for add/delete to get around the replace
> missing problem.
>
> I've explained that in more details on
> https://btrfs.wiki.kernel.org/index.php/FAQ#Can_I_use_RAID.5B56.5D_on_my_Btrfs_filesystem.3F
> but it may not be a great page to link to.
> Ok, I just made a new nice page for you:
> https://btrfs.wiki.kernel.org/index.php/RAID56
>
> Do you think it would be ok to link to
> https://btrfs.wiki.kernel.org/index.php/RAID56#Parity_Rebuilds_and_Advanced_Disk_Replacement
> in the btrfs replace man page?
That's very nice for you making a new wiki page.
IMO it's OK to link to the URL.

Thanks,
Qu
>    
>> +It is recommended to see `btrfs-device`(8) for more details about btrfs device
>> +management.
>> +
>>   SUBCOMMAND
>>   ----------
>>   'start' [-Bfr] <srcdev>|<devid> <targetdev> <path>::
>> @@ -74,3 +77,4 @@ further details.
>>   SEE ALSO
>>   --------
>>   `mkfs.btrfs`(8),
>> +`btrfs-device`(8),
>> -- 
>> 1.9.2
> The rest looks good.
>
> Thank you,
> Marc

Re: [PATCH 1/2] btrfs-progs: Add device management related paragraph.

[David Sterba]

On Thu, Apr 10, 2014 at 11:10:48PM -0700, Marc MERLIN wrote:
> > --- a/Documentation/btrfs-replace.txt
> > +++ b/Documentation/btrfs-replace.txt
> > @@ -13,6 +13,9 @@ DESCRIPTION
> >  -----------
> >  'btrfs replace' is used to replace btrfs managed devices with other device.
> 
> I would add a quick line here saying that it's not currently supported for
> RAID5/6, and to see btrfs-device for add/delete to get around the replace
> missing problem.

I've added the quick note when committing the patch.

Re: [PATCH 1/2] btrfs-progs: Add device management related paragraph.

[Marc MERLIN]

On Fri, Apr 11, 2014 at 07:36:28PM +0200, David Sterba wrote:
> On Thu, Apr 10, 2014 at 11:10:48PM -0700, Marc MERLIN wrote:
> > > --- a/Documentation/btrfs-replace.txt
> > > +++ b/Documentation/btrfs-replace.txt
> > > @@ -13,6 +13,9 @@ DESCRIPTION
> > >  -----------
> > >  'btrfs replace' is used to replace btrfs managed devices with other device.
> > 
> > I would add a quick line here saying that it's not currently supported for
> > RAID5/6, and to see btrfs-device for add/delete to get around the replace
> > missing problem.
> 
> I've added the quick note when committing the patch.

Thanks both.

Generally, would you agree to putting more links to the wiki in man pages
since man pages are not forever but sure take a long time to update on the
installed based and the wiki can be up to date for everyone right away?
(I'm not saying to remove info from the man pages, but more something like
"btrfs is changing quickly, more up to date information can be found on the
wiki page for
raid56: https://btrfs.wiki.kernel.org/index.php/RAID56
or
btrfsck: https://btrfs.wiki.kernel.org/index.php/Btrfsck
btrfs restore: https://btrfs.wiki.kernel.org/index.php/Restore

Thanks,
Marc
-- 
"A mouse is a device used to point at the xterm you want to type in" - A.S.R.
Microsoft is to operating systems ....
                                      .... what McDonalds is to gourmet cooking
Home page: http://marc.merlins.org/  

Re: [PATCH 1/2] btrfs-progs: Add device management related paragraph.

[Qu Wenruo]

-------- Original Message --------
Subject: Re: [PATCH 1/2] btrfs-progs: Add device management related 
paragraph.
From: Marc MERLIN <marc@merlins.org>
To: dsterba@suse.cz, Qu Wenruo <quwenruo@cn.fujitsu.com>, 
linux-btrfs@vger.kernel.org
Date: 2014年04月12日 01:52
> On Fri, Apr 11, 2014 at 07:36:28PM +0200, David Sterba wrote:
>> On Thu, Apr 10, 2014 at 11:10:48PM -0700, Marc MERLIN wrote:
>>>> --- a/Documentation/btrfs-replace.txt
>>>> +++ b/Documentation/btrfs-replace.txt
>>>> @@ -13,6 +13,9 @@ DESCRIPTION
>>>>   -----------
>>>>   'btrfs replace' is used to replace btrfs managed devices with other device.
>>> I would add a quick line here saying that it's not currently supported for
>>> RAID5/6, and to see btrfs-device for add/delete to get around the replace
>>> missing problem.
>> I've added the quick note when committing the patch.
> Thanks both.
>
> Generally, would you agree to putting more links to the wiki in man pages
> since man pages are not forever but sure take a long time to update on the
> installed based and the wiki can be up to date for everyone right away?
> (I'm not saying to remove info from the man pages, but more something like
> "btrfs is changing quickly, more up to date information can be found on the
> wiki page for
> raid56: https://btrfs.wiki.kernel.org/index.php/RAID56
> or
> btrfsck: https://btrfs.wiki.kernel.org/index.php/Btrfsck
> btrfs restore: https://btrfs.wiki.kernel.org/index.php/Restore
>
> Thanks,
> Marc
That's pretty nice and helpful.
But one of my concern is that wiki changes are not shown as patches in 
mail list and somewhat
independent from btrfs-progs,
so if some developers changed the behavior of RAID56/btrfsck/restore, he 
or she may only modify the man page
but not wiki page.

Any good idea to synchronise wiki pages and man pages?

Thanks,
Qu

Re: wiki vs man pages

[Marc MERLIN]

On Mon, Apr 14, 2014 at 09:16:44AM +0800, Qu Wenruo wrote:
> >Generally, would you agree to putting more links to the wiki in man pages
> >since man pages are not forever but sure take a long time to update on the
> >installed based and the wiki can be up to date for everyone right away?
> >(I'm not saying to remove info from the man pages, but more something like
> >"btrfs is changing quickly, more up to date information can be found on the
> >wiki page for
> >raid56: https://btrfs.wiki.kernel.org/index.php/RAID56
> >or
> >btrfsck: https://btrfs.wiki.kernel.org/index.php/Btrfsck
> >btrfs restore: https://btrfs.wiki.kernel.org/index.php/Restore
> >
> >Thanks,
> >Marc
> That's pretty nice and helpful.
> But one of my concern is that wiki changes are not shown as patches in 
> mail list and somewhat
> independent from btrfs-progs,
> so if some developers changed the behavior of RAID56/btrfsck/restore, he 
> or she may only modify the man page
> but not wiki page.
> 
> Any good idea to synchronise wiki pages and man pages?

You raise a good question.

I think the wiki should not be there to list all the options that are in the
man page. As a result, the wiki should not get out of sync with man pages.

The wiki can explain how to use the tools, like some of the pages I listed
above, or this page
http://marc.merlins.org/perso/btrfs/2014-03.html#Btrfs-Tips_-Btrfs-Scrub-and-Btrfs-Filesystem-Repair

A page like this explains what your options are, and what it recommended
including links to other resources.
Man pages are more "these are the options to use this specific program".
In turn the man page cannot be very long and explain all the scenario or
explain how this tools works with other tools, so it can point to the wiki
that has HOWTOs.

So to answer your question, I would say that the man pages should indeed be
updated as the programs/binaries get updated, whereas the wiki pages can get
updated as needed and refer to bugs in the kernel, or missing features, or
features that just got added/improved in kwere kernels.
And also like in the page above, generally give an overview of parts of
btrfs.

Does that make sense?

Marc
-- 
"A mouse is a device used to point at the xterm you want to type in" - A.S.R.
Microsoft is to operating systems ....
                                      .... what McDonalds is to gourmet cooking
Home page: http://marc.merlins.org/  

Re: wiki vs man pages

[Qu Wenruo]

-------- Original Message --------
Subject: Re: wiki vs man pages
From: Marc MERLIN <marc@merlins.org>
To: Qu Wenruo <quwenruo@cn.fujitsu.com>
Date: 2014年04月14日 09:45
> On Mon, Apr 14, 2014 at 09:16:44AM +0800, Qu Wenruo wrote:
>>> Generally, would you agree to putting more links to the wiki in man pages
>>> since man pages are not forever but sure take a long time to update on the
>>> installed based and the wiki can be up to date for everyone right away?
>>> (I'm not saying to remove info from the man pages, but more something like
>>> "btrfs is changing quickly, more up to date information can be found on the
>>> wiki page for
>>> raid56: https://btrfs.wiki.kernel.org/index.php/RAID56
>>> or
>>> btrfsck: https://btrfs.wiki.kernel.org/index.php/Btrfsck
>>> btrfs restore: https://btrfs.wiki.kernel.org/index.php/Restore
>>>
>>> Thanks,
>>> Marc
>> That's pretty nice and helpful.
>> But one of my concern is that wiki changes are not shown as patches in
>> mail list and somewhat
>> independent from btrfs-progs,
>> so if some developers changed the behavior of RAID56/btrfsck/restore, he
>> or she may only modify the man page
>> but not wiki page.
>>
>> Any good idea to synchronise wiki pages and man pages?
> You raise a good question.
>
> I think the wiki should not be there to list all the options that are in the
> man page. As a result, the wiki should not get out of sync with man pages.
>
> The wiki can explain how to use the tools, like some of the pages I listed
> above, or this page
> http://marc.merlins.org/perso/btrfs/2014-03.html#Btrfs-Tips_-Btrfs-Scrub-and-Btrfs-Filesystem-Repair
>
> A page like this explains what your options are, and what it recommended
> including links to other resources.
> Man pages are more "these are the options to use this specific program".
> In turn the man page cannot be very long and explain all the scenario or
> explain how this tools works with other tools, so it can point to the wiki
> that has HOWTOs.
>
> So to answer your question, I would say that the man pages should indeed be
> updated as the programs/binaries get updated, whereas the wiki pages can get
> updated as needed and refer to bugs in the kernel, or missing features, or
> features that just got added/improved in kwere kernels.
> And also like in the page above, generally give an overview of parts of
> btrfs.
>
> Does that make sense?
>
> Marc
Thanks for your explanation, as for short, man page is showing 
specifications and wiki explain more use cases/internal mechanism things.
I'll add the links to the man pages.

Thanks,
Qu

Re: [PATCH 1/2] btrfs-progs: Add device management related paragraph.

[Liu Bo]

On Fri, Apr 11, 2014 at 10:43:52AM +0800, Qu Wenruo wrote:
> Add device management related paragraph to better explain btrfs device
> management.
> 
> Cc: Marc MERLIN <marc@merlins.org>
> Signed-off-by: Qu Wenruo <quwenruo@cn.fujitsu.com>
> ---
>  Documentation/btrfs-balance.txt |  3 +++
>  Documentation/btrfs-device.txt  | 42 +++++++++++++++++++++++++++++++++++++++++
>  Documentation/btrfs-replace.txt |  4 ++++
>  3 files changed, 49 insertions(+)
> 
> diff --git a/Documentation/btrfs-balance.txt b/Documentation/btrfs-balance.txt
> index 2289fdf..1b1861c 100644
> --- a/Documentation/btrfs-balance.txt
> +++ b/Documentation/btrfs-balance.txt
> @@ -14,6 +14,8 @@ DESCRIPTION
>  'btrfs balance' is used to balance chunks in a btrfs filesystem across
>  multiple or even single device.
>  
> +See `btrfs-device`(8) for more details about the effect on device management.
> +
>  SUBCOMMAND
>  ----------
>  <path>::
> @@ -75,3 +77,4 @@ further details.
>  SEE ALSO
>  --------
>  `mkfs.btrfs`(8),
> +`btrfs-device`(8)
> diff --git a/Documentation/btrfs-device.txt b/Documentation/btrfs-device.txt
> index 20d7bcd..474d411 100644
> --- a/Documentation/btrfs-device.txt
> +++ b/Documentation/btrfs-device.txt
> @@ -14,6 +14,46 @@ DESCRIPTION
>  'btrfs device' is used to control the btrfs devices, since btrfs can be used
>  across several devices, 'btrfs device' is used for multiple device management.
>  
> +DEVICE MANAGEMENT
> +-----------------
> +Btrfs filesystem is capable to manage multiple devices.
> +
> +Btrfs filesystem use different profiles to manage different RAID level, and
> +use balance to rebuild chunks, also devices can be added/removed/replace
> +online.

s/use/uses/g

> +
> +Profile::
> +Btrfs filesystem use data/metadata profiles to manage allocation/duplication
> +mechanism. Profiles like RAID level can be assigned to data and metadata separately.

ditto.

Good update.

-liubo

> ++
> +See `mkfs.btrfs`(8) for more details.
> +
> +RAID level::
> +Btrfs filesystem supports most of the standard RAID level: 0/1/5/6/10.
> +RAID levels can be assigned at mkfs time or online.
> ++
> +See `mkfs.btrfs`(8) for mkfs time RAID level assign and `btrfs-balance`(8) for
> +online RAID level assign.
> +
> +Balance::
> +`btrfs-balance`(8) subcommand can be used to balance or rebuild chunks to the
> +desired profile.
> ++
> +Due to the fact that balance can rebuild/recovery chunks according to its RAID
> +duplication if possible, so when using RAID1/5/6/10 with some devices failed
> +and you just added a new device to btrfs using `btrfs-device`(8), you should
> +run `btrfs-balance`(8) to rebuild the chunks.
> ++
> +See `btrfs-balance`(8) for more details.
> +
> +Device add/remove/replace::
> +Device can be added/removed using `btrfs-replace`(8) subcommand and replaced
> +using `btrfs-replace`(8).
> ++
> +When device is removed or replaced, btrfs will do the chunk rebuild if needed.
> ++
> +See `btrfs-replace`(8) and this man page for more details.
> +
>  SUBCOMMAND
>  ----------
>  'add' [-Kf] <dev> [<dev>...] <path>::
> @@ -73,3 +113,5 @@ further details.
>  SEE ALSO
>  --------
>  `mkfs.btrfs`(8),
> +`btrfs-replace`(8),
> +`btrfs-balance`(8)
> diff --git a/Documentation/btrfs-replace.txt b/Documentation/btrfs-replace.txt
> index 8c5dcc4..15a46c2 100644
> --- a/Documentation/btrfs-replace.txt
> +++ b/Documentation/btrfs-replace.txt
> @@ -13,6 +13,9 @@ DESCRIPTION
>  -----------
>  'btrfs replace' is used to replace btrfs managed devices with other device.
>  
> +It is recommended to see `btrfs-device`(8) for more details about btrfs device
> +management.
> +
>  SUBCOMMAND
>  ----------
>  'start' [-Bfr] <srcdev>|<devid> <targetdev> <path>::
> @@ -74,3 +77,4 @@ further details.
>  SEE ALSO
>  --------
>  `mkfs.btrfs`(8),
> +`btrfs-device`(8),
> -- 
> 1.9.2
> 
> --
> To unsubscribe from this list: send the line "unsubscribe linux-btrfs" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/2] btrfs-progs: Add device management related paragraph.

[David Sterba]

On Fri, Apr 11, 2014 at 05:16:22PM +0800, Liu Bo wrote:
> > +DEVICE MANAGEMENT
> > +-----------------
> > +Btrfs filesystem is capable to manage multiple devices.
> > +
> > +Btrfs filesystem use different profiles to manage different RAID level, and
> > +use balance to rebuild chunks, also devices can be added/removed/replace
> > +online.
> 
> s/use/uses/g
> 
> > +
> > +Profile::
> > +Btrfs filesystem use data/metadata profiles to manage allocation/duplication
> > +mechanism. Profiles like RAID level can be assigned to data and metadata separately.
> 
> ditto.

Both fixed at commit time.

Thanks.

Re: [PATCH 1/2] btrfs-progs: Add device management related paragraph.

[Qu Wenruo]

Thanks for fixing the problems.

Qu
-------- Original Message --------
Subject: Re: [PATCH 1/2] btrfs-progs: Add device management related 
paragraph.
From: David Sterba <dsterba@suse.cz>
To: Liu Bo <bo.li.liu@oracle.com>
Date: 2014年04月12日 01:34
> On Fri, Apr 11, 2014 at 05:16:22PM +0800, Liu Bo wrote:
>>> +DEVICE MANAGEMENT
>>> +-----------------
>>> +Btrfs filesystem is capable to manage multiple devices.
>>> +
>>> +Btrfs filesystem use different profiles to manage different RAID level, and
>>> +use balance to rebuild chunks, also devices can be added/removed/replace
>>> +online.
>> s/use/uses/g
>>
>>> +
>>> +Profile::
>>> +Btrfs filesystem use data/metadata profiles to manage allocation/duplication
>>> +mechanism. Profiles like RAID level can be assigned to data and metadata separately.
>> ditto.
> Both fixed at commit time.
>
> Thanks.