October 2012 - xwiki-devs@xwiki.org

[xwiki-devs] [Brainstorming] Handling "young" APIs for backward compatibility
by Vincent Massol 11 Feb '13

11 Feb '13

Hi devs, We have recently voted a rule where we said that we will do the following: * Always deprecate APIs * Always move them to Legacy modules * And when there's a technical issue to moving stuff to the Legacy module, only then, send a VOTE to remove an API (see http://markmail.org/message/tino4ngttflc5i3s) This means that from now on (starting on 26th of April 2012) we're not allowed to put excludes in CLIRR. However I've seen that we have added some CLIRR excludes after the vote was passed. I believe that the main issue we have is for "young" APIs that are not considered stable. Proposal 1: Internal package ========= * Young APIs must be located in the "internal" package till they become stable. I propose "internal" to reuse an existing package that we filter when testing for CLIRR. "internal" means that users should not use this API because it's considered unstable and can change at any time. * When a Young API is considered stable enough and we want to open it to public consumption then we move it from "internal" to its target package (that's easy to with IDEs). From that point forward any changes to them goes through the standard mechanism of deprecation/legacy. * If we want to add a new method to an existing public API then this should not be considered a "young" API. It's just an addition to an existing API and thus goes directly to the deprecation/legacy cycle. * We need to be careful to isolate "young" APIs from public API so that users don't inadvertently use "young" unstable APIs by mistake. If not possible then directly go through the deprecation/legacy cycle. The advantage of this proposal is that it doesn't change our current practices and is very easy to verify through CLIRR. Proposal 2: Experimental package ========= Another possibility I can think of is to introduce a new "experimental" package instead of reusing the "internal" one. It has the advantage of being able to follow "young" APIs and ensure they don't stay in that state indefinitely, while still allowing the user who uses it to notice it's experimental. Proposal 3: Experimental Annotation ========= Another idea is to just use an @Experimental javadoc tag for experimental code. It has the advantage of using the target package but it has drawbacks: * It's impossible for users to notice that they're using Experimental APIs since when they import a class they won't see anything that'll tell them they're using a "young" API * It's almost impossible to tell CLIRR to exclude those APIs from its checks. The only way to do this is to modify the source code of the CLIRR plugin AFAIK. Thus we would need to exclude those manually using CLIRR excludes and thus before we release we would need to go over the full list of CLIRR excludes to ensure the excludes listed are only for "young" APIs marked "experimental". Note that I mentioned javadoc tag and not annotation because I believe we need to add information about when the Experimental API was first introduced so that we eventually move it as a proper API by removing the Experimental tag. Maybe we would need a rule such as: keep that tag for less or equal to 3 full minor releases (i.e. 6 months). WDYT? Any other idea? Thanks -Vincent

8 25

[xwiki-devs] [Contrib] xwiki-application-mailarchive
by Jeremie BOUSQUET 08 Feb '13

08 Feb '13

Dear community, I would like to request for a new contrib project to store the Mail Archive application I'm currently writing. Name: xwiki-application-mailarchive Description: A mailing-list archive application. - For now a GitHub project to store sources should be fine. My username on GitHub is "jbousque". - For Jira it might be useful to have a project once the application is released "officially", that is still not the case. Meanwhile the generic project is ok for me. - There is a specific page in Design space on xwiki.org : http://dev.xwiki.org/xwiki/bin/view/Design/MailArchiveApplication , but for now no extension has been added. I would like if possible to test my extension (automatic install with dependencies) before publishing it The Design page also gives some info about the current state and progress, and some screenshots. There is many remaining work, but it begins to look like something usable. The bad side is the lack of unit tests most of all ... A question : the groupId "org.xwiki.contrib" is to be used, do I have to use this exact groupId or can there be sublevels if needed ? If so I would use org.xwiki.contrib.mailarchive as groupId. Thanks, Jeremie

6 87

[xwiki-devs] [PROPOSAL] So what do we do for our Maven projects names
by Thomas Mortagne 25 Jan '13

25 Jan '13

Hi devs, In order to automate the update of extensions imported from https://github.com/xwiki/ we need to have nothing to modify when an import is done. The last remaining thing is the name on which there is a debate is the name. Right now the name we have in our maven project looks like "XWiki Commons - Extension - Repository - Maven" so that's what we get when importing this project or when viewing it in EM UI. Some of us want to keep this idish name for Maven build but don't like it when displaying extension. I recently introduced a way to overwrite some extension related informations like the name based on properties. So here are the choices we have: 1) Do nothing which mean display "XWiki Commons - Extension - Repository - Maven" in EM UI and extensions.xwiki.org 2) Change our naming in Maven <name> property for it to be more a name than an id that would looks good in EM UI 3) Keep the same naming for Maven <name> and overwrite it everywhere using <xwiki.extension.name> property So, WDYT ? The one that makes the more sense to me is 2) so my +1 goes to this one. Frankly I don't care too much having the current id based display of the summary of built modules in Maven build and I personally won't have any issue to know what name correspond to what project (but that's because I know them well, I can understand new dev could be a bit more lost). Then: * +0 for 3) to +0 (I don't like too much having this special case everywhere in our Maven pom.xml) * -0 for 1) (I agree that it does not looks very nice as a display name). -- Thomas Mortagne

4 11

[xwiki-devs] [Brainstorming] Colocated Functional Test (CFT)
by Vincent Massol 22 Nov '12

22 Nov '12

Hi devs, I've started an experiment to have colocated functional tests (CFT), which means having the functional tests located where the functional domain sources are located instead of in XE. For example for the linkchecker module we have the following directories: xwiki-platform-linkchecker/ |_ xwiki-platform-linkchecker-refresher (JAR) |_ xwiki-platform-linkchecker-ui (XAR) |_ xwiki-platform-linkchecker-tests (functional tests) The rationale for this was: * Have everything about a functional domain self-contained (source and all tests) * Making it easy to run only tests for a given functional domain * Move page objects to the functional domain too Here are some findings about this experiment: A - It takes about 30 seconds to generate the adhoc packaging and start XWiki. This would be done for each module having functional tests compared to only once if all tests were executed in XE B- The package mojo created to generate a full packaging is quite nice and I plan to reuse it in lots of other places in our build (distributions, database, places where we need XWiki configuration files) C- We will not be able to run platform builds in Maven multithreaded mode since it would mean that several XWiki instance could be started at the same time on the same port D- The colocated functional test module Solutions/ideas: * One idea to overcome A and C would to have the following setup: ** Keep functional test modules colocated but have them generate a test JAR ** Still allow running functional tests from the colocated module (this makes it easy to verify no regression was introduced when making changes to a given domain) ** Have functional tests in XE depend on the colocated functional test module JARs and configure Jenkins to run all functional tests from XE only * Another solution to overcome C is to auto-discover the port to use in our XWiki startup script (and save it in a file so that the stop script can use it). I think the first proposal is the best one and brings the best of the 2 worlds. WDYT? Thanks -Vincent

4 10

[xwiki-devs] Thoughts on new model proposal
by Caleb James DeLisle 16 Nov '12

16 Nov '12

Hi, I took a look at the new model proposal and there are a few questions and suggested changes. https://github.com/xwiki/xwiki-platform/blob/feature-newmodel/xwiki-platfor… Should this be a String rather than a Java UUID type? https://github.com/xwiki/xwiki-platform/blob/feature-newmodel/xwiki-platfor… If we use getChildren() rather than getChildReferences(), we will be mangling the model with the database code which violates the MVC principle. Also we run the risk of encouraging users to walk the tree looking for the entity it wants rather than creating a reference to it and using that. Walking the tree would obviously incur enormous unnecessary database load. https://github.com/xwiki/xwiki-platform/blob/feature-newmodel/xwiki-platfor… Do we want to continue with the concept of the global variable representing the "current" document? I'm currently not brimming with alternative ideas but the heavy reliance on the XWikiContext has lead to a lot of inter-modular communication which makes oldcore difficult to maintain, perhaps we can prevent this in the new model. https://github.com/xwiki/xwiki-platform/blob/feature-newmodel/xwiki-platfor… I would rather this have a name which doesn't collide with a java.lang class. When I see Object in a .java file I would like it to always mean java.lang.Object. https://github.com/xwiki/xwiki-platform/blob/feature-newmodel/xwiki-platfor… I like XClass better for this purpose, it is essentially a class and creating a new name which nobody has ever heard of will just steepen the learning curve and make things hard on newcomers. https://github.com/xwiki/xwiki-platform/blob/feature-newmodel/xwiki-platfor… Why not give the user direct access to the property without the intervening wrapper? https://github.com/xwiki/xwiki-platform/blob/feature-newmodel/xwiki-platfor… I don't like this. A Persistable is saved in a store by a user. Who is the user and where are they saving it? What if I want to have multiple stores? Must there be a global variable representing the store which is implied by this function? The comment and minorEdit fields are also a bit dubious, perhaps in the future they will make no sense, perhaps they should really be attributes of the Document, also the "attributes" parameter reminds me of this: http://geek-and-poke.com/2012/06/how-to-create-a-stable-api.html Finally, giving the document awareness of where and how it is stored violates the MVC boundries. I think we should not worry about the API which stores the Persistable when we are creating the model, the store API should be separate so that it can evolve while the model stays stable. https://github.com/xwiki/xwiki-platform/blob/feature-newmodel/xwiki-platfor… A session is essentially a transaction? If so why not call it Transaction? Also why does it extend Persistable? How do you persist a session? https://github.com/xwiki/xwiki-platform/blob/feature-newmodel/xwiki-platfor… Why does addSpace() not take a Space parameter? it makes sense to me that you would do: parent = storeApi.get(wikiRef, "SomeSpace", user); child = new DefaultSpace(); child.addDocument("ADocument", new DefaultDocument("This is content.")); parent.addSpace("ChildSpace", child); storeApi.save(parent, user); I'm just brainstorming here but this seems like a reasonable approach.. I noticed the lack of a User data type, is that just something which is planned for the future or is it intentionally missing? Thanks, Caleb

2 3

[xwiki-devs] [VOTE] Create new xwiki-platform-application/ module
by Vincent Massol 14 Nov '12

14 Nov '12

Hi devs, I'm writing functional tests for the FAQ app in platform and I wanted to write a test for verifying that the app registers itself in the app panel. The problem is that the app panel requires UI extensions and the app panel is currently located in the panels app. However I don't want to put that as a dependency on UI extensions in the panels app since no other panel need it. So the good answer is that the app panel is not correctly located. Actually the panels ui app should only contain the Panels.WenHome page and all other panels should be part of the other functional domains… So that brings me to this proposal which is: * Create a new xwiki-platform-application/ which represents the functional domain of wiki applications. * Have 3 submodules in it as follows: xwiki-platform-application/ |_ xwiki-platform-application-manager/ |_ xwiki-platform-application-manager-api/ |_ xwiki-platform-application-manager-ui/ |_ xwiki-platform-application-appwithinminutes/ |_ xwiki-platform-application-ui/ * ATM xwiki-platform-application-ui/ would contain only the Applications Panel but in the future the content of xwiki-platform-application-manager-ui/ should be merged with it and it should for example provide a UI to list all apps in the wiki. * In the future xwiki-platform-application-manager-api/ would also be renamed in xwiki-platform-application-api/ Here's my +1 Thanks -Vincent

4 3

[xwiki-devs] [VOTE] Add CLIRR exclude for 2 new methods in the workspace interface for 4.3M1
by Eduard Moraru 14 Nov '12

14 Nov '12

Hi devs, Since the current policy is to ask before adding a CLIRR exclude and since I did not ask when I applied GuillaumeD's pull request [1], I hereby ask for your vote whether it is ok to exclude the 2 new methods: - that allows the creation of workspaces using a different template than the default one - that lists workspace templates Since we are tight with time (Fabio needs to finish the 4.3M1 release), this issue should be settled ASAP. Also, please note that the Workspace API is still young (and pretty basic), as far as I am concerned, and it is bound to get updated in the future. Here's my +1 Thanks, Eduard -------- [1] https://github.com/xwiki/xwiki-platform/pull/70

7 8

Re: [xwiki-devs] [VOTE] Move history when moving stuff from repositories of "xwiki" organization
by Denis Gervalle 14 Nov '12

14 Nov '12

Le 9 mars 2012 16:59, "Vincent Massol" <vincent(a)massol.net> a écrit : > > > On Mar 2, 2012, at 10:06 AM, Denis Gervalle wrote: > > > On Wed, Feb 29, 2012 at 08:19, Vincent Massol <vincent(a)massol.net> wrote: > > > >> Hi, > >> > >> On Feb 28, 2012, at 12:17 PM, Thomas Mortagne wrote: > >> > >>> Hi devs, > >>> > >>> Since I plan to move some stuff from platform to commons I would like > >>> to know what you think of the history in this case. > >>> > >>> Pros including history: > >>> * can access easily the whole history of a moved file. > >> > > > > This is really an important matter, especially for those joining the > > project. When you follow XWiki from "outside", and not in a continuous > > manner, the history is of great value to understand why stuffs are like > > they are, and what you may do, or not when moving forward. > > The history is not lost. If you do a join (all active repos) you still have it. I do not know what you means by joining all repos, but I would be surprise to see the IDE find its way between them. I even wonder how it could be possible. > > >> But sometimes > >>> changing packages etc make too much difference for git to see it's > >>> actually the same file so you loose it anyway. > >> > > > > If you simply change the package name, and nothing else, it is really > > unlikely to happen. > > > > > >>> > >>> Cons including history: > >>> * double the history which make tools like ohloh indicate wrong > >> informations > >> > > > > Sure, the stats will be broken, but what is the matter. This is not > > cheating, just a misfeature in Ohloh, since the commit are just identical, > > something they may notice. IMO, this is the matter of the statistical tools > > to improve that. > > Can you tell me how to implement this because right now my GitHub tool doesn't do that and I don't know how to do it? If I had to implement it, I will probably use some hashing method to be able to recognize similar commits, since there effectively no link between them. But my main remarks that the statistics are broken, not the way we use git. > > >>> * it's a lot easier to move without history > >> > > > > There should be some tools to improve that point or we may write one, once > > for all. So this is not a real cons either. > > It's really hard to copy history in Git. It's almost impossible to do it right. You have to remember the full history and it's just too hard. I would be really disappointed to have to conclude that. There is probably some edge cases, but most of the time there is clever work around. You have to talk to Sergiu :-) > > >>> WDYT ? > >>> > >>> Even if it was looking a bit weird to me at first I'm actually +1 to > >>> not move the history in this case. > >> > >> +1, FTR I'd be -0, close to -1 to move it. If/when the source repository > >> is removed for one reason or another, then we might want to import its > >> history somewhere. > >> > > > > Seems we are really opposite on this one, since I am close to -1 to not > > move it. > > Sorry but that's the current practice :) It's also the easiest one. Until we have Git, there were no better way. This does not means that we should not improve our practice. By the way, it was not my thread, if Thomas has asked, it means that the current practice was not so current. > > > Statistics is really less valuable IMO, it is a small interest compare to > > code history, that I have use a lot, especially when I have join the > > project and follow sparingly. > > I can say exactly the same thing as you said above. It's just a question of tools since the history is not lost. It's still there in our active repos. There is absolutely no link between these histories. It is not only a question of tools. Moreover, requiring querying all active repositories to have a proper history completely defeat the purpose of having separate repositories. I do not see the comparison with my remark above. Git has been made for versionning, not for statistics, it is not my fault. > > > So the general rule for me is: Copy history when the source repository is > >> removed/deleted/not used anymore. > > How many times have you done this? I believe 0 times since I don't think you'd be so much in favor if you had tried it. I suggest you try it a few times on your own projects first :) It's really hard to do it right and very time consuming. When I have copied the security component from contrib, I have done so. I hope that I am not alone. And, frankly, it was not so hard, compare to the advantage you have. > > > You never know what will happen to a repository in the future, so this > > rules is somewhat a hope on the future, no more. And remembering that we > > may loose history if we do some change in the old repository, is for me > > like hoping you will remember my birthday ;) > > I don't agree with this at all. Again we're not loosing history. If a repo is removed then its history is copied I agree about that. I would like to know how you do that after the facts? > > >>> Eduard was proposing to include in the first commit of the new > >>> repository the id of the last commit containing the files (basically > >>> the id of the parent of the commit deleting the files) in the old > >>> repository so that it's easier to find it. I'm +1 for this. > >> > > > > But you loose all the benefits of the IDE tools that brings history of a > > selection automatically and that are really useful. > > A huge majority of xwiki's history is already lost to IDEs (when we moved from SVN) even though the SVN history was moved. Even Git itself doesn't follow the history when you move stuff around. Said differently it's alwasy possible to find the history but the IDE and "standard" tool don't follow it. It does so far better since we move to Git and it is really a valuable tool. Do you means that because in a few case, the history may be broken, that we should not try to have it as complete as possible? > > > Moreover, if the history is rewritten due to a change in structure later, > > the hash may be broken. > > Not sure I understand this one. In Git, nothing is fully permanent, that is all I say. > > You should really measure the cost of what you propose Denis. It's really hard to do. Prove me that is more cost than the one newcommers has to enter the project. Maybe you do not value history so much because you have by your own experience of the project a good knowledge of what happen in the past. When I dig in some code, I always found history valuable to understand why that piece of code is not written the way I may have expected and why I should not got that way. If Thomas conclude it is too hard to be done, and not just some developer's lazyness, I would understand; but I do not agree that it should not be done just because it breaks statistics or we think it is too hard. This is why I suggest a tools that do it once for all. I would be really disappointed of Git if we had to conclude this. Thanks, Denis > > Thanks > -Vincent > > > So having a broken history is hardening the task of those who want to > > participate. A great value compare to the statistics IMO. > > > > -- > > Denis Gervalle > > SOFTEC sa - CEO > > eGuilde sarl - CTO > > _______________________________________________ > > devs mailing list > > devs(a)xwiki.org > > http://lists.xwiki.org/mailman/listinfo/devs > > _______________________________________________ > devs mailing list > devs(a)xwiki.org > http://lists.xwiki.org/mailman/listinfo/devs

5 8

[xwiki-devs] [VOTE] Dynamically registered wiki translations
by Thomas Mortagne 10 Nov '12

10 Nov '12

Hi devs, Following the discussion about general architecture of the new localization module here is a more detailed proposal for the dynamically registered wiki translations pages. Here is how I propose to indicate that a document contains key=value pair translations: * put an object of class "XWiki.TranslationDocumentClass" * set the "visibility" field to "Global", "Current wiki", "Current user" As for the content of the document it will stay the same as in preferences based documents for now. I have other fields in mind for later (on demand, translation message syntax, etc.) but this is a 4.3 proposal here. WDYT ? Here is my +1. -- Thomas Mortagne

9 19

[xwiki-devs] Fwd: Github tracker. was: Re: [xwiki-users] New Realtime collaborative editing extension.
by Ludovic Dubost 07 Nov '12

07 Nov '12

This should have been for devs Envoyé de mon iPhone Début du message transféré : > Expéditeur: Ludovic Dubost <ludovic(a)xwiki.com> > Date: 23 octobre 2012 09:19:55 UTC+02:00 > Destinataire: XWiki Users <users(a)xwiki.org> > Objet: Github tracker. was: Re: [xwiki-users] New Realtime collaborative editing extension. > > Just a quick. You seem to introduce a practice to use the github tracker instead of xwiki.org jira's > > Not sure it's a good thing. I'm sure Vincent will agree > > Ludovic > > > Envoyé de mon iPhone > > Le 23 oct. 2012 à 04:17, Caleb James DeLisle <calebdelisle(a)lavabit.com> a écrit : > >> One other thing, please report the features which you want and what you imagine as >> best on the github tracker, it's easier to close an issue as "won't fix" than it is >> to remember an important issue which nobody wrote down ;) >> >> Thanks >> Caleb >> >> On 10/22/2012 10:14 PM, Caleb James DeLisle wrote: >>> Hi, >>> >>> Thanks for the complement. >>> >>> I just updated it and fixed issue #1. Thanks for reporting it. >>> Somehow showing who else is editing, showing where they are editing in the document >>> and allowing the user to spawn a chat window with other editors on the page are all >>> interesting possibilities. Right now I think the thing to do is decide where there >>> is the most bang for your buck in terms of feature value and get an idea of what's >>> most natural for the user. >>> >>> Thanks, >>> Caleb >>> >>> >>> On 10/19/2012 07:59 AM, Ryszard Łach wrote: >>>> Great work! >>>> >>>> It looks like good starting point to give xwiki the main (at least for >>>> me) feature, that makes googledoc sometimes more suitable for >>>> collaborative editing. It would be really great, if your editor would >>>> show somehow, where the other editor (person) is now, where is his >>>> cursor. Maybe a highlight (the whole line) showing the other's cursor >>>> placement? >>>> Do you plan to work on such improvements? >>>> >>>> R. >>>> >>>> _______________________________________________ >>>> users mailing list >>>> users(a)xwiki.org >>>> http://lists.xwiki.org/mailman/listinfo/users >>> >>> >>> _______________________________________________ >>> users mailing list >>> users(a)xwiki.org >>> http://lists.xwiki.org/mailman/listinfo/users >> >> >> _______________________________________________ >> users mailing list >> users(a)xwiki.org >> http://lists.xwiki.org/mailman/listinfo/users

5 18