On Apr 11, 2012, at 5:35 PM, Vincent Massol wrote:
> > On Apr 11, 2012, at 5:28 PM, Eduard Moraru wrote: > >> On Wed, Apr 11, 2012 at 6:14 PM, Vincent Massol <[email protected]> wrote: >> >>> >>> On Apr 11, 2012, at 4:11 PM, Vincent Massol wrote: >>> >>>> Hi, >>>> >>>> On Apr 11, 2012, at 3:31 PM, Eduard Moraru wrote: >>>> >>>>> Hi Vincent, >>>>> >>>>> On Thu, Apr 5, 2012 at 7:19 PM, Vincent Massol <[email protected]> >>> wrote: >>>>> >>>>>> Hi devs, >>>>>> >>>>>> Now that we're starting to use the Extension Manager (EM) we need to be >>>>>> careful about the Description and Names we use in our pom.xml since >>> they're >>>>>> used by the EM to display information to the user. They're also used >>> by the >>>>>> XR application to import extensions located in maven repository into >>>>>> extensions.xwiki.org (EXO). >>>>>> >>>>>> Right now our names are of the type shown here: >>>>>> https://gist.github.com/2311321 >>>>>> >>>>>> For example: >>>>>> [INFO] XWiki Commons - Extension - Parent POM ............ SUCCESS >>> [0.004s] >>>>>> [INFO] XWiki Commons - Extension - API ................... SUCCESS >>> [2.066s] >>>>>> [INFO] XWiki Commons - Extension - Handler - Parent POM .. SUCCESS >>> [0.017s] >>>>>> [INFO] XWiki Commons - Extension - Handler - JAR ......... SUCCESS >>> [0.133s] >>>>>> [INFO] XWiki Commons - Extension - Repository - Parent POM SUCCESS >>>>>> [0.004s] >>>>>> [INFO] XWiki Commons - Extension - Repository - Aether ... SUCCESS >>> [0.132s] >>>>>> [INFO] XWiki Commons - Extension - Repository - XWiki .... SUCCESS >>> [0.006s] >>>>>> [INFO] XWiki Commons - Extension - Repository - XWiki model SUCCESS >>>>>> [0.188s] >>>>>> [INFO] XWiki Commons - Extension - Repository - XWiki api SUCCESS >>> [0.010s] >>>>>> [INFO] XWiki Commons - Extension - Repository - XWiki handler SUCCESS >>>>>> [0.024s] >>>>>> >>>>>> These names are not nice names for users. Actually they're more IDs >>> than >>>>>> names. And having the users see those in our livetable on EXO isn't >>> nice >>>>>> for example. Nor is it nice if they see them in the EM UI. >>>>>> >>>>>> I thus propose that we change the way we use names in our pom.xml to >>> use >>>>>> English-readable names, without any "XWiki" prefix. >>>>>> >>>>>> For example, for the example show above we could have: >>>>>> >>>>>> Extensions >>>>>> Extension API >>>>>> Extension Handlers >>>>>> JAR Extension Handler >>>>>> Extension Repositories >>>>>> Aether Extension Repository >>>>>> XWiki Extension Repository >>>>>> XWiki Extension Repository Model >>>>>> XWiki Extension Repository API >>>>>> XWiki Extension Repository Handler >>>>>> >>>>> >>>>> I`m not trilled at all about seeing this in my maven console. We lose >>> any >>>>> (1) consistency of display and (2) module membership. >>>>> >>>>> (1) is pretty obvious since "Extensions" is at plural (and misleading >>> btw, >>>>> since it's just a parent module), "Extension API" is at singular, "JAR >>>>> Extension Handler" is not prefixed by the module and so on. Plus, >>> imagine >>>>> if the extensions view is sorted by extension name (not currently >>>>> implemented). >>>>> >>>>> About (2), I consider it to be useful extremely to a user to get an idea >>>>> from a glance of where that "thing" (that his extension is or depends >>> on) >>>>> actually is and where it comes from. >>>>> >>>>> If you look at the other 3rd party extenions, you will see "Commons X" >>> (ok, >>>>> module X comes from Commons -- "Commons BeanUtils"), "Jetty :: X" (ok, >>>>> module X comes from Jetty -- "Jetty :: IO Utility") and so on. I >>> understand >>>>> that this can be seen as a maven limitation, but all the other projects >>> are >>>>> working around it like we also did. >>>>> >>>>> On the other hand, projects like Commons are library projects that have >>>>> pretty much a flat structure (<Project Name> <Module Name>). Since in >>> XWiki >>>>> pretty much everything is an extension, the Core Extensions section (EM >>> UI) >>>>> will be flooded with xwiki modules which are pretty complex in hierarchy >>>>> and which will confuse the user when they are all displayed on the same >>>>> level. >>>>> >>>>> I`m -0, towards -1 on the initial proposal. >>>>> >>>>> If we really think that we have a problem on this area, I propose that >>> we >>>>> introduce a convention for module names that both displays module >>>>> membership but does not overdo it (a combination of what you propose and >>>>> what we currently have): >>>>> <ProjectName> - <Feature/ModuleName> - <SubModulePrettyName> >>>>> >>>>> Example: >>>>> XWiki Commons - Extension - API >>>>> XWiki Commons - Extension - Aether Repository >>>>> XWiki Commons - Extension - XWiki Repository Model >>>>> XWiki Commons - Extension - XWiki Repository Handler >>>>> XWiki Platform - Annotations - UI >>>>> XWiki Platform - Blog >>>>> <-- has no submodule >>>>> XWiki Rendering - Macro - HTML >>>>> etc. >>>>> >>>>> The main idea was to make sure that we don`t have any extra levels in >>>>> <SubModulePrettyName>. IMO, 3 levels is decent from a user's POV and >>> should >>>>> be enough for devs when structuring their code. If you think about it, >>>>> that`s pretty much what we already do in the maven project structure. >>>>> >>>>> If the extensions view only displayed XWiki extensions (without 3rd >>> party >>>>> modules from other projects) then your initial proposal would have been >>>>> relevant from the user's POV (though still not good for developers). >>>>> >>>>> Maven is at hart a development tool. Yes, we`ve decided to reuse it on >>> the >>>>> user side as well, but we should not trade a working dev practice for a >>>>> pretty name that will not even be useful to the user anyway. I fail to >>>>> envision a practical usecase for the development process where the maven >>>>> console displays pretty names. It will just be a string blob that will >>> make >>>>> things harder. >>>>> >>>>> WDYT? >>>> >>>> <Answer on naming> >>>> >>>> I was the one who defined both the names we use in our pom.xml, the id >>> in our pom.xml and our directory names. I have chosen to use a structure >>> that represents the full name in all places: >>>> >>>> * For names: XWiki Commons - Extension - API >>>> * For ids: xwiki-commons-extension-api >>>> * For directories: xwiki-commons-extension-api/ >>>> >>>> I've been told that we prefer to use simpler names since the hierarchy >>> already contains the information about the project. This proposal (which is >>> not yet implemented but decided AFAIK) initially came from the fact that >>> long directory names don't work on Windows. >>>> >>>> It's the same for names. You don't need to have the full "path" in a >>> pom.xml name to know where it's coming from since it's contained in a >>> pom.xml which has a location. >>>> >>>> * For names: Extension API >>>> * For ids: xwiki-commons-extension-api (we need the full name for id >>> since we use a fixed groupid ATM. We could drop the first path though if we >>> really and have only "extension-api" since the group id is >>> "org.xwiki.commons" but since this is a technical id I'm not sure it's a >>> good idea and it's not the topic of this mail anyway ;)) >>>> * For directories: api/ (more precisely: commons/extension/api/) >>>> >>>> Thus using short names is not shocking at all. To be honest I doubt >>> anyone is really using the name when developing. Having a short name >>> wouldn't be an issue. >>> >>> FTR Maven POM Reference (http://maven.apache.org/pom.html) says the >>> following about the <name> element: >>> >>> " >>> name: Projects tend to have conversational names, beyond the artifactId. >>> The Sun engineers did not refer to their project as "java-1.5", but rather >>> just called it "Tiger". Here is where to set that value. >>> " >>> >>> The name is not supposed to be an id. There's artifactid for that. >>> >> >> Again, an example of a top level project. Works well for small top level >> projects too. But I don`t think it works that well for submodules of bigger >> projects. >> >> Anyway, my vote is non-binding but I still think it will lose developer >> value in favour of an insignificant user value. > > Actually I think quite the opposite: this change is an insignificant change > for the developer but a major advantage for the user. As Thomas mentioned to me, it would be nice if Maven could be configured to display the artifactId in the Reactor Summary… However, that's not implemented and while we could provide our own distribution of Maven, I don't think we should do that ;) Another possibility that we discussed with Thomas a few days ago would be to have a format like this: <technical name> - <conversational name> So for example for the HMTL Macro that would be: <name>XWiki Rendering - Macros - HTML Macro</name> And in the EM UI we would display only the last part of the name (ie what comes after the last "-"): "HTML Macro". For ex if we take my initial example: [INFO] XWiki Commons - Extension - Parent POM ............ SUCCESS [0.004s] [INFO] XWiki Commons - Extension - API ................... SUCCESS [2.066s] [INFO] XWiki Commons - Extension - Handler - Parent POM .. SUCCESS [0.017s] [INFO] XWiki Commons - Extension - Handler - JAR ......... SUCCESS [0.133s] [INFO] XWiki Commons - Extension - Repository - Parent POM SUCCESS [0.004s] [INFO] XWiki Commons - Extension - Repository - Aether ... SUCCESS [0.132s] [INFO] XWiki Commons - Extension - Repository - XWiki .... SUCCESS [0.006s] [INFO] XWiki Commons - Extension - Repository - XWiki model SUCCESS [0.188s] [INFO] XWiki Commons - Extension - Repository - XWiki api SUCCESS [0.010s] [INFO] XWiki Commons - Extension - Repository - XWiki handler SUCCESS [0.024s] We would need to change the names to: - XWiki Commons - Extension - Extensions - XWiki Commons - Extension - Extension API - XWiki Commons - Extension - Handler - Extension Handlers - XWiki Commons - Extension - Handler - JAR Extension Handler - XWiki Commons - Extension - Repository - Extension Repositories - XWiki Commons - Extension - Repository - Aether Extension Repository - XWiki Commons - Extension - Repository - XWiki Extension Repository - XWiki Commons - Extension - Repository - XWiki - XWiki Extension Repository Model - XWiki Commons - Extension - Repository - XWiki - XWiki Extension Repository API - XWiki Commons - Extension - Repository - XWiki - XWiki Extension Repository Handler It will lead to longer names with redundancies but maybe that's ok if it satisfies both use cases? -Vincent > Again, having a user see "XWiki Rendering - Macros - HTML Macro" is way less > nice than him seeing "HTML Macro", don't you agree about that? > > And again the path can be shown beneath as in: > > HTML Macro > (coming from XWiki Rendering / Macros) <-- displayed in smaller letters and > in light gray (for ex) > > Thanks > -Vincent > >> Thanks, >> Eduard >> >> >>> >>> Thanks >>> -Vincent >>> >>>> </Answer on naming> >>>> >>>> I think the main point where I have not been clear is that there has >>> never been any intention of having XWiki modules displayed flat in the >>> Extensions Home Page livetable :) >>>> >>>> If that had been the intention then we would definitely have needed a >>> long name to group stuff together. But again it's not the intention at all. >>> Why not? Simply because it doesn't scale and would mean showing lots of >>> stuff to users, flooding them. >>>> >>>> So we need to talk about what we're doing now and future… >>>> >>>> * Now: We only display modules that are either relevant to the user (ie >>> that they can download) or modules that are used as documentation points. >>> We're not planning to import all modules. The idea is to continue importing >>> only extensions useful to users or top level modules to hold the >>> documentation for that module. >>>> >>>> * Future: I think the best representation for the future will be the >>> following: >>>> - a treeview when you wish to browser everything. So to take the example >>> of "XWiki Rendering - Macros - HTML Macro" it would be under the XWiki >>> Rendering/Macros/HTML Macro tree nodes >>>> - if you start typing letters in this treeview-livetable widget you'll >>> see all the extensions matching the letters you type, in a flat view (no >>> longer hierarchical) >>>> - we will continue to have tags to provide categorizations of >>> extensions: for example "'Macros", "Applications", "LDAP", "HTML", etc >>>> - we will also need a view (probably the default - the treeview would be >>> a tab to click to get it) which is a flat view listed by user ratings. So >>> the most used extensions will get better ratings and will show at the top, >>> thus making the more technical or less used extensions got at the bottom of >>> the list. >>>> - When displayed in flat view, we could easily display the location of >>> the extension on the next line in smaller characters and in grey color >>> instead of black for example (to make it less visible) >>>> >>>> To conclude: it's very important that we have a pretty name as the name. >>> This is the intent of Maven's pom.xml <name> tag. The hierarchy is provided >>> by the <parent> information and can easily be gathered and displayed, >>> whether you are in maven (mvn dependency:tree, your IDE) or in the EM UI. >>>> >>>> >>>>> P.S.: I`m +0 for the new proposal, since I am quite happy with the >>> current >>>>> setup. >>>> >>>> What new proposal? >>>> >>>> Thanks >>>> -Vincent >>>> >>>>> Thanks, >>>>> Eduard >>>>> >>>>> >>>>>> The alternative is to introduce a custom property in our pom.xm that >>> would >>>>>> be used by the EM and XR but that's not a good solution because it >>> means >>>>>> even more maintenance work. >>>>>> >>>>>> While not using technical id as names in our pom.xml is not as nice >>> when >>>>>> displayed in the Maven Reactor I feel it's still the best solution we >>> have. >>>>>> >>>>>> Here's my +1 >>>>>> >>>>>> Thanks >>>>>> -Vincent _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
