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