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. 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 > _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
