Date: Fri, 28 Jun 2013 14:36:45 +0200
From: Natanael Copa <ncopa@alpinelinux.org>
To: Dubiousjim <dubiousjim@gmail.com>
Cc: alpine-devel@lists.alpinelinux.org
Subject: Re: [alpine-devel] [PATCH 00/15] apk-tools UI fixes/refinements
Message-ID: <20130628143645.277c3eb5@ncopa-desktop.alpinelinux.org>
In-Reply-To: <cover.1372361242.git.dubiousjim@gmail.com>
References: <cover.1372361242.git.dubiousjim@gmail.com>
Precedence: list
Mime-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit

On Thu, 27 Jun 2013 15:28:45 -0400
Dubiousjim <dubiousjim@gmail.com> wrote:

> Some months ago, I patched apk-tools in various ways to (in my view) improve
> the UI and also to provide a logging mechanism. I've been using these in
> practice on my local machine. It's about time to rebase them against the
> current apk-tools git repo, and see if they can be incorporated upstream.
> 
> This set of patches has the UI tweaks. It'll take me a bit longer to
> rebase/test the logging patch against the current apk-tools sourcebase.
> 
> For the most part, these UI tweaks don't introduce anything that will break
> existing behavior---except in 1 place (or perhaps 1-and-a-half places), which
> I'll describe below. However, I have introduced some new short/long option
> flags for existing functionality, and in some places have declared the old
> flags "deprecated." In the current implementation, all that deprecation amounts
> to is that the usage message recommends the new flag; no warnings are output
> when the old flag is in fact used.

I am a bit sceptic to this kind of changes. It basically means that
there are some things that simply cannot be used in scripts, unless we
provide a simple way for a script to fish out the apk scripting "api"
version.

Maybe introduce apk --api-version

if empty, then its current api, then whenever we change the scripting
'api' or output format, we bump the "api-version" number.

That way scripts has a way to deal with this kind of changes in future.

like:

apk_api="$(apk --api-version 2>/dev/null)"
: ${apk_api:=0}

if [ $apk_api -le 1 ]; then
	apk_mkindex="apk index";;
else
	apk_mkindex="apk mkindex";;
fi

$apk_mkindex *.apk .... etc

 
> 1. One set of changes is that we move some options that are now listed in the
> "generic options" usage block, but which don't in fact apply to all applets,
> into the applet-specific option set for the applets that use them. This applies
> to -U/--update-cache, --purge, and --clean-protected.

I think this is good. I am not 100% sure but I think that the short form id integer
might need to be universally unique.
 
> 2. A second change we introduce is that we accept "apk mkindex" to mean what
> "apk index" already means, and prefer the former. This makes its behavior more
> memorable,at least for me, and stops me from wondering why functions like "apk
> version -l" aren't underneath the "apk index" applet instead.

I like this change. lets keep both for a while for backwards compat and
later we can remove 'apk index'.
 
> A lot of changes try to impose some more consistency on the option flags,
> especially the short option flags, either with other applets or with familiar
> POSIX utilities.

I like this.
 
> 3. One of those sets of changes concerns the various flags for recursing
> upwards or downwards in the dependency tree.
> 
> Let me frame my overview of those changes with this observation: POSIX tools
> mostly use -R for recursive operations (consider chmod, chown, chgrp, ls, cp,
> rm). cp also accepts -r, sometimes with equivalent behavior to -R. But not all
> implementations can be relied on to treat "cp -R" and "cp -r" equivalently; and
> where they diverge, it's usually the first that's wanted. (See the OS X cp.1
> manpage.) rm also accepts -r, and can be relied on to treat "rm -R" and "rm -r"
> equivalently. But the IEEE/Open Group's rm.1p manpage recommends using "rm -R",
> for consistency with other utilities. The Gnu *grep utilities (which are also
> the defaults on some BSD systems) also treat -R and -r equivalently. As it
> happens, BusyBox *grep only honors -r, but I will be submitting a patch to
> BusyBox upstream to also accept -R, as the Gnu versions do.
> 
> The only remaining familiar utilities to ONLY accept -r for recursive
> functionality are diff and rsync. On the other hand, a whole range of utilities
> use -r for other purposes (consider date, touch, ls, sort, Gnu and BusyBox sed,
> xargs, vi, and so on).
> 
> So the strongest existing pattern here seems to be to use "-R" to mean
> "recurse".

Keep in mind that in apk context, there are 3 different
kinds of "recurse":
 * recurse filedirectories:
     apk audit --recursive

 * recurse dependencies downward/forward/by depends:
     apk fetch --recursive

 * recurse reverse dependencies (upward/backward/by required-by):
     apk del --rdepends


> But what does a recursive operation in a dependency tree amount to? We could
> mean "also operate on the specified package's dependencies." Let's use
> --depends as the long-form name of that option. (As apk-tools sometimes does;
> currently it also sometimes uses --recursive here instead.)

What if you want list 'depends' without recursing? (apk info <show the depends>)

how about --recurse-depends?

> Or we could mean
> "also operate on the packages that depend on the specified package." Let's use
> --rdepends as the long-form name of that option. (For "reverse-depends", not
> "recursive depends.")

What if you only want know the direct related package upwards (think
when an abi change for a library and you want to know what packages
needs to be rebuilt)

how about --recurse-rdepends?

> It would be confusing to have -R be the short-form option
> for "--depends", and some other letter be the short-form option for
> "--rdepends". So I propose we consistently use "-R" in the apk-tools namespace
> to mean "--rdepends", that is, to operate recursively UPWARDS in the dependency
> graph (towards packages that have more dependencies). Sometimes apk-tools
> currently uses "-d" as the short-form option for the other direction
> (--depends). But other times apk-tools uses -d differently. For consistency
> with -R, I propose we use "-D" here instead.
> 
> So in general:
> 
>   -D/--depends means to also apply an operation to the packages that the
>   specified package depends on, that is, downwards in the dependency
>   graph
> 
>   -R/--rdepends means to also apply an operation to the packages that
>   depend on the specified package, that is, upwards in the dependency
>   graph

those 2 alone does not cover all cases.

Here is a summary of all options that are recursive:

Options for del command:
  -r, --rdepends          Recursively delete all top-level reverse dependencies
                          too
Options for fix command:
  -d, --depends           Fix all dependencies too

Options for fetch command:
  -R, --recursive         Fetch the PACKAGE and all its dependencies

Options for audit command:
  -r, --recursive         List individually all entries in new directories


Here are relevant --depends/--rdepends options that are non-recursive:

Options for info command:
  -R, --depends           List packages that the PACKAGE depends on
  -r, --rdepends          List all packages depending on PACKAGE

Options for search command:
  -r, --rdepends          Print reverse dependencies of package



Note that for some commands only one direction of recurive dependencies
makes sense.
apk fetch - makes no sense with --recurse-rdepends
apk del - makes no sense with --recurse-depends

I think recursive operation makes no sense for apk info, but for apk
search, yes.

When i think of it, --recursive only make sense downwards in dependency
tree (similar when talking about directories in file system) with the
exception of 'apk del', so basically we could do:

-R, --recursive forward depends when dealing with dependencies or
                filesystem (possibly with exception of apk info, which
                always it is non-recursive)

-r for "reverse dependency" (only apk del operates recursively on this,
   but it always operates "recursively")


The above summary would be change to (* means a breakage from current):
Options for del command:
  -r, --rdepends          Recursively delete all top-level reverse dependencies
                          too
Options for fix command:
* -R, --recursive         Recursively fix all dependencies too

Options for fetch command:
  -R, --recursive         Recursively fetch the PACKAGE and all its dependencies

Options for audit command:
* -R, --recursive         Recursively list individually all entries in new directories


Since -R now means 'recursive' and -d already means 'description' we
could change apk info's non recursive to -D

Options for info command:
* -D, --depends           List packages that the PACKAGE depends on

But i am also ok with keeping 'apk info -R' as an exception. (i think
-R was originally taken to correspond to BSD's pkg_info -R)


how does that sound?

> These patches roll out that change across the apk applets and usage messages,
> while still accepting the old short and long options too, where these exist. We
> just declare some of the old options as "deprecated" in the usage messages.
> 
> There's only one place where this requires us to introduce a breaking change:
> currently "apk info -R" is interpreted as "apk info --depends", but these
> changes will make it be interpreted in the other direction, as "apk info
> --rdepends". I hope this small deviation from existing behavior is tolerable.

I am sceptic to this because:
* it will break scripts
* the ouput is similar so it might be difficult to spot the change.
  (think a stressful situation, you log on to an old box via ssh, you
  do 'apk info -R' and need to make a fast desicion...)

> One awkwardness I haven't resolved is that in most cases, both the -D and -R
> options are recursive: -D operates on your dependencies, and their
> dependencies, and so on. However in "apk info", I think -D and -R only apply to
> a single level of dependencies: only your direct dependencies, and so on. It'd
> be nice if we could make this work recursively too (and perhaps had a flag to
> limit the recursion to only a single level). But that isn't implemented here.

I prefer -R mean recursive rather than -D. I don't like that -R goes
opposite what it means now.

> 4. Another option-related change is that we now let "apk search -x" mean "apk
> search -e/--exact", and prefer the former. This is consistent with the -x flag
> on grep, and also steps away from the conflicting meaning of "-e" in "apk
> info".

I'm ok with this. Makes sense.

> There are some other changes as well, which should be noted in the individual
> commits. Here I'm just trying to give the high-level overview, not an
> exhaustive description.
> 
> Here are some further ideas for changes that I DON'T try to implement here, but
> I submit for consideration/discussion.

I'll comment those in a separate email/thread.


-nc


---
Unsubscribe:  alpine-devel+unsubscribe@lists.alpinelinux.org
Help:         alpine-devel+help@lists.alpinelinux.org
---