On Thu, 15 Sep 2011 17:46:11 Vandonderen Casper (Nokia-MP-Qt/Oslo) wrote: > On 9/15/11 9:05 AM, "ext Alan Alpert" <[email protected]> wrote: > >On Thu, 15 Sep 2011 14:45:59 ext Mark Constable wrote: > >> On 2011-09-15 05:07 AM, [email protected] wrote: > >> > >When they're used like that, then the people who work on those > >> > >examples already have that repo - and not some generic repo - > >> > >cloned. The changes to the example will likely follow directly > >> > >from API changes leading to the aforementioned CI problems. On > >> > >top of that you won't be sole maintainer of it, which makes some > >> > >of the advantages less necessary. > >> > > >> > Just to put more weight behind Alan's argument. I fully agree with > >> > his statement. The disadvantages are far more significant than the > >> > benefits. I would go as far as saying that the main purpose of the > >> > example is quick testing and the doc aspect is just sugar on top. > >> > Let's not make the current repo split situation worse than it is > >> > already. > >> > >> OTOH it could be useful for the developer to know their example code > >> will build and run outside of their cosey checkout and, perhaps, > >> encourage them to interact with the other code examples as well. It's > >> a bit more bother for individual developers but the overall health of > >> all the examples may improve. > > > >You're thinking of demos. Examples should be so simple and single-minded > >that > >it's pointless to interact with other examples. Or even other > >repositories. > > > >Now if we had demos again, they could interact with other examples and > >verify > >that things run against a full and common checkout or something. But the > >extra > >complexity is only going to confuse the matter for a example that's > >trying to > >demonstrate/test a single thing with utmost clarity. > > Before Open Governance it was decided between the team leads in the Qt > offices that Qt5 would only have examples, since the old wording for demos > and examples was not clear.
Judging from what I've seen of the reactions from team leads down here, you may have missed an office... Perhaps we can revisit the decision after Open Governance? Give the chief maintainer a nice easy problem to get him started? > Also the decision was made that all examples that go into the Qt Project > should have documentation, no matter how simple or complex they are. A > 'hello world' is therefore the same as someone building a full strategy > game in QML. (That this is outside of open governance is IMHO beside the > point, since I think we can agree that it is a good idea to have > documentation for examples) This is a dig against the abysmal Plasma Patrol docs isn't it? :P > The documentation for the examples should normally go into the qtdoc > module (which means that you would have to change your own module, the > qtexamples module and the qtdoc module). We can agree that all > documentation for examples would live in the qtexamples module. > > That means that we move from 'module + qtdoc' to 'module + qtexamples' for > example content. As I understood it, the documentation for the examples should go into the module in question - not qtdoc. We still have a doc directory in the module structure that we can happily use for that, and the people writing the example have to be the ones to write at least the first draft of the documentation. If they aren't writing it now because they can't be bothered, then moving it to another repository is only going to make things worse. So I don't think the example docs should be in qtdoc - keep them with the examples (which I think should be with the code). That means that we move from 'module' to 'module + qtexamples' for example content. No longer such an appealing switch. -- Alan Alpert Senior Engineer Nokia, Qt Development Frameworks _______________________________________________ Qt5-feedback mailing list [email protected] http://lists.qt.nokia.com/mailman/listinfo/qt5-feedback
