Mark btrfsctl deprecated

Mark btrfsctl deprecated

[Goffredo Baroncelli <kreijack@libero.it>]

Hi Chris,

what do you think about marking deprecate the "btrfsctl" program ?

A lot of people make patch involving both btrfs command and btrfsctl command, 
spending a lot of effort. 

Initially we can put a warning in the btrfctl command which suggest to use the 
btrfs command. and after XX month (six ?) we could remouve the command at all. 
The same for the other utilities like btrfs-show, btrfs-vol....

Of course this is applicable if there is no evidence of regression of btrfs vs 
btrfsctl.

Regards
G.Baroncelli

Re: Mark btrfsctl deprecated

[David Nicol]

I am certainly not in a position to answer for Chris Mason, but I am
happy to share my response to the question, coming from a perspective
of being somewhat obsessive about not breaking back-compat.

Let's not. As I am certainly within the "lot of people" in question,
having just done exactly that, I found the two programs -- with very
different styles -- to not be much of a block, and providing two
examples instead of one of code that invokes an ioctl seems fine.

Ideally, everyone who needs to use an ioctl will simply write and
compile a C program that does what they need -- ha ha.

I see no reason to break legacy code (such as it is) that uses
btrfsctl instead of btrfs for a user-space tool to invoke ioctls.
Calling the tool "btrfs" is actually a little confusing.



On Fri, Oct 22, 2010 at 7:02 AM, Goffredo Baroncelli
<kreijack@libero.it> <kreijack@libero.it> wrote:
> Hi Chris,
>
> what do you think about marking deprecate the "btrfsctl" program ?
>
> A lot of people make patch involving both btrfs command and btrfsctl command,
> spending a lot of effort.
>
> Initially we can put a warning in the btrfctl command which suggest to use the
> btrfs command. and after XX month (six ?) we could remouve the command at all.
> The same for the other utilities like btrfs-show, btrfs-vol....
>
> Of course this is applicable if there is no evidence of regression of btrfs vs
> btrfsctl.
>
> Regards
> G.Baroncelli

Re: Mark btrfsctl deprecated

[Goffredo Baroncelli]

On Monday, 25 October, 2010, David Nicol wrote:
> I am certainly not in a position to answer for Chris Mason, but I am
> happy to share my response to the question, coming from a perspective
> of being somewhat obsessive about not breaking back-compat.

I agree with this sentence; in fact I suggested to mark the program 
"deprecated" with a warning and to remove it after some months.

> 
> Let's not. As I am certainly within the "lot of people" in question,
> having just done exactly that, I found the two programs -- with very
> different styles -- to not be much of a block, and providing two
> examples instead of one of code that invokes an ioctl seems fine.

If you need an example program put it into a directory called "example"... for 
example :)

> 
> Ideally, everyone who needs to use an ioctl will simply write and
> compile a C program that does what they need -- ha ha.
> 
> I see no reason to break legacy code (such as it is) that uses
> btrfsctl instead of btrfs for a user-space tool to invoke ioctls.
> Calling the tool "btrfs" is actually a little confusing.

Ideally "btrfs" had the goal to replace "btrfsctl" (and some other programs). 
This for a lot of reason: btrfctl is buggy, un-maintainable, doesn't handle 
very well a lot of errors..
A lot of posts in this mailing lists reports errors due to a misunderstanding 
of the syntax and behavior of btrfs filesystem and btrfsctl. I hoped writing 
"btrfs" to improve this situation.

Every patch needs a checking and is a potential source of conflicts. Why 
double the effort maintaining two equivalent programs ?

The package btrfs-tools needs a lot of care:
- the INSTALL file still reports that is not possible to remove a subvolume
- a lot of program are not documented (what is the meaning of btrfs-zero-log 
?)
- "btrfs dev scan" and "btrfs -a" try to read CDROM and Floppy looking for a 
btrfs filesystem: only waste of time
- [...]

I think that is better to improve the btrfs-progs and not to update btrfsctl.

Only my 2C

regards
G.Baroncelli



> 
> 
> 
> On Fri, Oct 22, 2010 at 7:02 AM, Goffredo Baroncelli
> <kreijack@libero.it> <kreijack@libero.it> wrote:
> > Hi Chris,
> >
> > what do you think about marking deprecate the "btrfsctl" program ?
> >
> > A lot of people make patch involving both btrfs command and btrfsctl 
command,
> > spending a lot of effort.
> >
> > Initially we can put a warning in the btrfctl command which suggest to use 
the
> > btrfs command. and after XX month (six ?) we could remouve the command at 
all.
> > The same for the other utilities like btrfs-show, btrfs-vol....
> >
> > Of course this is applicable if there is no evidence of regression of 
btrfs vs
> > btrfsctl.
> >
> > Regards
> > G.Baroncelli
> --
> 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
> 


-- 
gpg key@ keyserver.linux.it: Goffredo Baroncelli (ghigo) <kreijack@inwind.it>
Key fingerprint = 4769 7E51 5293 D36C 814E  C054 BF04 F161 3DC5 0512

Re: Mark btrfsctl deprecated

[Chris Mason]

On Tue, Oct 26, 2010 at 07:32:14PM +0200, Goffredo Baroncelli wrote:
> 
> The package btrfs-tools needs a lot of care:
> - the INSTALL file still reports that is not possible to remove a subvolume
> - a lot of program are not documented (what is the meaning of btrfs-zero-log 
> ?)
> - "btrfs dev scan" and "btrfs -a" try to read CDROM and Floppy looking for a 
> btrfs filesystem: only waste of time
> - [...]
> 
> I think that is better to improve the btrfs-progs and not to update btrfsctl.

I'd agree, the btrfsctl command is more than a little awkward, and the
btrfs command is pretty much better in every way.

-chris

[RFC PATCH] Deprecate btrfsctl, btrfs-show, btrfs-vol

[Goffredo Baroncelli]

[-- Attachment #1: Type: Text/Plain, Size: 6356 bytes --]

Hi all,

the patch below deprecates the following programs

* btrfsctl
* btrfs-vol
* btrfs-show

the reason is simple, these programs are superseded by the btrfs utility,
both in terms of documentation, usability and bug. The goal is to avoid 
to duplicate codes and avoid update two programs.

What I am asking here is a comment about the WARNINGs and suggestions about 
the policy to adopt in deprecating these programs.
My suggestions are:
- put a warning in the documentation and in the program (see below)
- "freeze" the programs avoiding to add new functionality to the 
  "old utilities". 
- after six month remove the old utilities programs from the btrfs-progs 
  package

The aim is to support the old systems but discourage to use the old tools.

If btrfs would show regression respect the old tools, I am happy to know and 
I will work to solve the issues.

The patch adds a warning in the man pages, in the INSTALL file and in the 
programs.

$ ./btrfsctl 
**
** WARNING: this program is considered deprecated
** Please consider to switch to the btrfs utility
**
no valid commands given
usage: btrfsctl [ -d file|dir] [ -s snap_name subvol|tree ]
                [-r size] [-A device] [-a] [-c] [-D dir .]
        -d filename: defragments one file
        -d directory: defragments the entire Btree
        -s snap_name dir: creates a new snapshot of dir
        -S subvol_name dir: creates a new subvolume
        -r [+-]size[gkm]: resize the FS by size amount
        -A device: scans the device file for a Btrfs filesystem
        -a: scans all devices for Btrfs filesystems
        -c: forces a single FS sync
        -D: delete snapshot
        -m [tree id] directory: set the default mounted subvolume to the [tree id] or the 
directory


Below the patch, but it is possible to pull the changes from:

 	http://cassiopea.homelinux.net/git/btrfs-progs-unstable-all.git

branch

	btrfs-deprecated

Comments are welcome.

G.Baroncelli

 INSTALL             |    5 +++++
 btrfs-show.c        |    5 +++++
 btrfs-vol.c         |    5 +++++
 btrfsctl.c          |    5 +++++
 man/btrfs-show.8.in |    3 +++
 man/btrfsctl.8.in   |    3 +++
 6 files changed, 26 insertions(+)


diff --git a/INSTALL b/INSTALL
index 16b45a5..cbde78f 100644

--- a/INSTALL
+++ b/INSTALL
@@ -24,10 +24,15 @@ e2fsprogs-devel from various distros.
 Building the utilities is just make ; make install.  The programs go
 into /usr/local/bin.  The commands available are:
 
+btrfs: control program to manage the filesystem.
+
 mkfs.btrfs: create a filesystem
 
 btrfsctl: control program to create snapshots and subvolumes:
 
+	NOTE: this utility is deprecated. Please consider to switch
+	to the btrfs utility (see above)
+
 	mount /dev/sda2 /mnt
 	btrfsctl -s new_subvol_name /mnt
 	btrfsctl -s snapshot_of_default /mnt/default
diff --git a/btrfs-show.c b/btrfs-show.c
index c49626c..8210fd2 100644
--- a/btrfs-show.c
+++ b/btrfs-show.c
@@ -117,6 +117,11 @@ int main(int ac, char **av)
 	int ret;
 	int option_index = 0;
 
+	printf( "**\n"
+		"** WARNING: this program is considered deprecated\n"
+		"** Please consider to switch to the btrfs utility\n"
+		"**\n");
+
 	while(1) {
 		int c;
 		c = getopt_long(ac, av, "", long_options,
diff --git a/btrfs-vol.c b/btrfs-vol.c
index 4ed799d..fe6f240 100644
--- a/btrfs-vol.c
+++ b/btrfs-vol.c
@@ -78,6 +78,11 @@ int main(int ac, char **av)
 	struct btrfs_ioctl_vol_args args;
 	u64 dev_block_count = 0;
 
+	printf( "**\n"
+		"** WARNING: this program is considered deprecated\n"
+		"** Please consider to switch to the btrfs utility\n"
+		"**\n");
+
 	while(1) {
 		int c;
 		c = getopt_long(ac, av, "a:br:", long_options,
diff --git a/btrfsctl.c b/btrfsctl.c
index 92bdf39..d20c96a 100644
--- a/btrfsctl.c
+++ b/btrfsctl.c
@@ -107,6 +107,11 @@ int main(int ac, char **av)
 	char *fullpath;
 	u64 objectid = 0;
 
+	printf( "**\n"
+		"** WARNING: this program is considered deprecated\n"
+		"** Please consider to switch to the btrfs utility\n"
+		"**\n");
+	
 	if (ac == 2 && strcmp(av[1], "-a") == 0) {
 		fprintf(stderr, "Scanning for Btrfs filesystems\n");
 		btrfs_scan_one_dir("/dev", 1);
diff --git a/man/btrfs-show.8.in b/man/btrfs-show.8.in
index dd0b147..cb98b68 100644
--- a/man/btrfs-show.8.in
+++ b/man/btrfs-show.8.in
@@ -3,6 +3,9 @@
 btrfs-show \- scan the /dev directory for btrfs partitions and print results.
 .SH SYNOPSIS
 .B btrfs-show
+.SH NOTE
+.B btrfs-show
+is deprecated. Please consider to switch to the btrfs utility.	
 .SH DESCRIPTION
 .B btrfs-show
 is used to scan the /dev directory for btrfs partitions and display brief
diff --git a/man/btrfsctl.8.in b/man/btrfsctl.8.in
index c2d4488..558b484 100644
--- a/man/btrfsctl.8.in
+++ b/man/btrfsctl.8.in
@@ -10,6 +10,9 @@ btrfsctl \- control a btrfs filesystem
 [ \fB \-A\fP\fI device\fP ]
 [ \fB \-a\fP ]
 [ \fB \-c\fP ]
+.SH NOTE
+.B btrfs-show
+is deprecated. Please consider to switch to the btrfs utility.
 .SH DESCRIPTION
 .B btrfsctl
 is used to control the filesystem and the files and directories stored. It is the tool to 
create a new snapshot for the filesystem.


On Tuesday, 26 October, 2010, Chris Mason wrote:
> On Tue, Oct 26, 2010 at 07:32:14PM +0200, Goffredo Baroncelli wrote:
> > 
> > The package btrfs-tools needs a lot of care:
> > - the INSTALL file still reports that is not possible to remove a subvolume
> > - a lot of program are not documented (what is the meaning of btrfs-zero-log 
> > ?)
> > - "btrfs dev scan" and "btrfs -a" try to read CDROM and Floppy looking for a 
> > btrfs filesystem: only waste of time
> > - [...]
> > 
> > I think that is better to improve the btrfs-progs and not to update btrfsctl.
> 
> I'd agree, the btrfsctl command is more than a little awkward, and the
> btrfs command is pretty much better in every way.
> 
> -chris
> 
> --
> 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
> 


-- 
gpg key@ keyserver.linux.it: Goffredo Baroncelli (ghigo) <kreijack@inwind.it>
Key fingerprint = 4769 7E51 5293 D36C 814E  C054 BF04 F161 3DC5 0512

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 190 bytes --]