vocabulary and text representation of module and dependencies

[Xavier Hanin <xa...@gmail.com>]

Hi,

In the world of dependency management we often need to speak about modules
involved in a dependency relationship. If A depends on B, we sometimes need
to talk about A not as A, but as "the module depending on B", or more
generally "the module having a dependency on another module". Same for B, we
sometimes need to refer to it as "the module on which A depends" or "the
module on which another module depends. As being a non native English
speaker, I often wonder if there are words to talk about these idioms
clearly and concisely. According to what I found recently over the web, some
are talking about:
A: depender, or dependent
B: dependee, or dependency

I think it would be fine if we could agree on some words, and reference them
in the documentation (on the terminology page for instance), and use them
when necessary. For instance the dependency documentation [1] talks about
master configuration, using depender or dependent (or whatever we agree on)
would probably make sense.

This lead me to other questions about conciseness when speaking about
modules and dependencies. Having a good and uniform text representation of
concepts involved in Ivy would be helpful when discussing them in the
mailing lists and documentation (or in console output). We often use '->'
(dash greater than) as a text representation for a dependency; and it's
already used for configuration dependencies (aka configuration mapping).
Maybe we could agree on that, and maybe also on text representation of:
1) a module without revision
2) a module with revision
3) a module with (some) configurations
4) a module with revision and (some) configurations
5) a module's artifact
6) a module's artifact with revision

Maybe taking an example will make things easier to understand:
Let's talk about Ant:
org=org.apache.ant
name=ant
rev=1.7
(some) configurations=master,compile,runtime
artifact=
  name=ant
  type=source (I take an example where type and ext are different)
  ext=jar

ATM in Ivy (according to #toString() on org.apache.ivy.core.module.idclasses):
#1 [ org.apache.ant | ant ]
#2 [ org.apache.ant | ant | 1.7 ]
#3 ?
#4 ?
#5 [ org.apache.ant | ant ] ant.source
#6 [ org.apache.ant | ant | 1.7 :: ant . jar ( source ) ]

#6 used to be much more confusing in 1.4 (something like [ org.apache.ant |
ant ]/ant.jar if I remember well), this is already an improvement. #5 is
very bad. And overall the representations are not very concise.

So, could we discuss about options and see if we can agree on something
clear and concise enough to be used both in Ivy itself and in the
documentation and mailing list?

I don't have time right now to cast some ideas, but go ahead!

Xavier

[1] http://ant.apache.org/ivy/history/trunk/ivyfile/dependency.html
-- 
Xavier Hanin - Independent Java Consultant
http://xhab.blogspot.com/
http://ant.apache.org/ivy/
http://www.xoocode.org/

Re: vocabulary and text representation of module and dependencies

[Xavier Hanin <xa...@gmail.com>]

On 11/1/07, Xavier Hanin <xa...@gmail.com> wrote:
>
> Hi,
>
> In the world of dependency management we often need to speak about modules
> involved in a dependency relationship. If A depends on B, we sometimes need
> to talk about A not as A, but as "the module depending on B", or more
> generally "the module having a dependency on another module". Same for B, we
> sometimes need to refer to it as "the module on which A depends" or "the
> module on which another module depends. As being a non native English
> speaker, I often wonder if there are words to talk about these idioms
> clearly and concisely. According to what I found recently over the web, some
> are talking about:
> A: depender, or dependent
> B: dependee, or dependency
>
> I think it would be fine if we could agree on some words, and reference
> them in the documentation (on the terminology page for instance), and use
> them when necessary. For instance the dependency documentation [1] talks
> about master configuration, using depender or dependent (or whatever we
> agree on) would probably make sense.
>
> This lead me to other questions about conciseness when speaking about
> modules and dependencies. Having a good and uniform text representation of
> concepts involved in Ivy would be helpful when discussing them in the
> mailing lists and documentation (or in console output). We often use '->'
> (dash greater than) as a text representation for a dependency; and it's
> already used for configuration dependencies (aka configuration mapping).
> Maybe we could agree on that, and maybe also on text representation of:
> 1) a module without revision
> 2) a module with revision
> 3) a module with (some) configurations
> 4) a module with revision and (some) configurations
> 5) a module's artifact
> 6) a module's artifact with revision
>
> Maybe taking an example will make things easier to understand:
> Let's talk about Ant:
> org=org.apache.ant
> name=ant
> rev=1.7
> (some) configurations=master,compile,runtime
> artifact=
>   name=ant
>   type=source (I take an example where type and ext are different)
>   ext=jar
>
> ATM in Ivy (according to #toString() on org.apache.ivy.core.module.idclasses):
> #1 [ org.apache.ant | ant ]
> #2 [ org.apache.ant | ant | 1.7 ]
> #3 ?
> #4 ?
> #5 [ org.apache.ant | ant ] ant.source
> #6 [ org.apache.ant | ant | 1.7 :: ant . jar ( source ) ]
>
> #6 used to be much more confusing in 1.4 (something like [ org.apache.ant| ant ]/ant.jar if I remember well), this is already an improvement. #5 is
> very bad. And overall the representations are not very concise.
>
> So, could we discuss about options and see if we can agree on something
> clear and concise enough to be used both in Ivy itself and in the
> documentation and mailing list?
>
> I don't have time right now to cast some ideas, but go ahead!


Here is a proposition for those text representations:
#1: org.apache.ant#ant
#2: org.apache.ant#ant;1.7.0
#3: org.apache.ant#ant[master,compile,build]
#4: org.apache.ant#ant;1.7.0[master,compile,build]
#5: org.apache.ant#ant!ant.jar(source)
#6: org.apache.ant#ant;1.7.0!ant.jar(source)

And a couple of shortcuts:
module id, when organization is obvious or reader don't care: #ant
#6 when type == ext: org.apache.ant#ant;1.7.0!ant.jar

So for instance if someone speaks about ant 1.7 which depends on xercesImpl
2.8.1, this could be written:
#ant;1.7.0 -> #xercesImpl;2.8.1

I think this would make reading logs easier, and speaking and documenting
some things easier (eg the unit test fixtures).

If we introduce a strict mode in names (where we forbid using # ; [ ] ( )
and ! in org/name/rev/conf/artifact/ext/type) then we could even parse these
text representations safely.

What do you think? Do you see any problem on using (in #toString()) and
documenting these representations? Maybe have some better ideas?

Xavier

Xavier
>
> [1] http://ant.apache.org/ivy/history/trunk/ivyfile/dependency.html
> --
> Xavier Hanin - Independent Java Consultant
> http://xhab.blogspot.com/
> http://ant.apache.org/ivy/
> http://www.xoocode.org/




-- 
Xavier Hanin - Independent Java Consultant
http://xhab.blogspot.com/
http://ant.apache.org/ivy/
http://www.xoocode.org/