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. 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
