Community
Participate
Working Groups
We would like to enhance the information available on the standard project information pages (e.g., http://www.eclipse.org/projects/project_summary.php?projectid=technology.dash) by having a standard machine readable project plan file format (e.g., XML). A standard format would allow us to extract information from each project's plan and show it on their information page as well as roll-up summaries across all projects as part of the annual release plan, the Roadmap, etc. This bug is opened to gather suggestions and input from the Eclipse project teams about what they would like to see (or not see) in a standard project plan format. So far, two different formats have been suggested: 1. An XML format containing something like: <plan> <theme name="Faster"> <theme name="Better"> <theme name="Cheaper"> <description> ...text... </description> <bug number="123456" type="committed"/> <bug number="123456" type="proposed"/> ...etc... 2. Having all plan items be bugs or enhancements in bugzilla and then using target milestones and keywords to indicate the plan and themes. For example, keywords like "theme_Faster" or "theme_Better". 3. Some combination of (1) and (2). Perhaps preambles and descriptions in XML (1) and lists of enhancements in bugzilla (2). ?? Looking at existing projects plans we find: (a) http://www.eclipse.org/eclipse/development/eclipse_project_plan_3_4.html Has a preamble. Has release deliverables (groups of bundles). Has milestone and dates. Has operating systems to be supported. Has internationalization description. Has compatibility with previous releases. Has work areas (themes) with committed, proposed, and deferred items. Most work areas are associated with bugs. Has an appendix. (b) http://wiki.eclipse.org/DTP_Enablement_Ganymede_Project_Plan Has a preamble. Has work areas grouped by company. Most are associated with bugs. (c) http://www.eclipse.org/modeling/emf/docs/dev-plans/emf_project_plan_2.4.html Has a preamble. Has release deliverables (groups of bundles). Has milestone and dates. Information mostly by indirection (English) from other project plans. Has operating systems to be supported. Information mostly by indirection (English) from other project plans. Has compatibility with previous releases. Has work areas (themes) with committed, proposed, and deferred items. All of these are done by dynamic bugzilla queries. (z) and so on. So the question to the Eclipse project community members is "do you have any other ideas?" Or, for these potential formats, do you have any refinements and clarifications? For example, for bugzilla (2) should all bugs aimed at a particular milestone be considered plan items or those bugs that are marked with a "theme_" keyword?
Obviously, we would provide an XSLT or PHP script to render the machine readable project plan on the website so that, of course, each project only needs to keep a single copy of their plan (the one in machine readable format).
(In reply to comment #1) > Obviously, we would provide an XSLT or PHP script to render the machine > readable project plan on the website so that, of course, each project only > needs to keep a single copy of their plan (the one in machine readable format). > Well, another option is to leverage the wiki where possible for some of this information. If you want a standard template you could create one. However, while I think a standard plan format might be good, it also starts to enforce a particular heavy weight approach to the development. I don't want to introduce process just for introducing process. The idea for any format would be to keep it agile enough and adaptable enough. Otherwise people are not going to use it and go back to their own ways of planning. Here is another format of a Requirements Plan for consideration: http://wiki.eclipse.org/XSL_Tools_Requirements
The point of having a standardized format is so that it's amenable to manipulation by tools that could help produce, for example, a collective plan for all the projects. Dave's wiki document does appear to be to a large extent composed as a list of bugzillas with some additional verbiage. I could imagine it being composed from an enumerated set of project themes along with the description of each them and then marking bugzillas to associate them with the themes. All the information about the bug itself could be contained in the bugzilla. The last thing we'd want to do is enforce a heavy weight approach. An approach that maps well to the actual day-to-day development activities seems best. That's why lists of bugzillas seems good. At least for EMF, we use bugzilla to drive all our activities. No commit to CVS is done without associating it with a bugzilla and in this way, we can generate release notes with each build and close the bugzillas that have been committed to that build. In this way, a plan document could be kept up-to-date as the plan items are completed. I think this is the type of workflow we should discuss as a group so that we arrive at a light weight process where the developer's daily activities in and of themselves provide the raw data for the plan document and will, at the end of the release, provide the data needed for the release review. We must come up with something that creates less work and results in less overhead such that the alternatives seem poor by comparison...
I don't mind basing plans on Bugzilla queries as long as it's possible to tell ahead of time what will actually make it into a release (so that clients can plan accordingly).
As Ed mentioned, a good number of projects are already planning using Bugzilla. WTP, for instance, has adopted the following rough process internally: 1. At the start of a yearly release, all of the enhancements are reviewed and the ones that are likely to get addressed in the following year are targeted to that release (the release, not a milestone). 2. At the start of each milestone, the teams pick out the enhancements that they are going to work on for that milestone. Those enhancements then get targeted to that milestone. 3. Developers are encouraged to use targets as a truthful communication tool and to be neither too conservative nor to aggressive when setting the targets. Basically, at least for WTP, if you were to query bugzilla, you would get the most accurate picture posible of what's planed and what's happening than you would by looking at the plan wiki. A lot of the WTP committers share my opinion that our plan wiki is needless duplication of content already represented in bugzilla, so getting people to update the wiki is an uphill battle (that's frequently lost by project leadership).
(In reply to comment #5) > Basically, at least for WTP, if you were to query bugzilla, you would get the > most accurate picture posible of what's planed and what's happening than you > would by looking at the plan wiki. A lot of the WTP committers share my opinion > that our plan wiki is needless duplication of content already represented in > bugzilla, so getting people to update the wiki is an uphill battle (that's > frequently lost by project leadership). That is assuming that all of the enhancements have been entered into bugzilla, which in my experience hasn't necessarily been the case across eclipse as a whole. So while I agree and would prefer bugzilla, it would be very very very important that everything was entered into bugzilla as much as possible. Several times a new feature has shown up into a milestone without there being a bugzilla before hand. Not saying that it's always the case but it happens more often than I like to see.
Dave, I can't emphasize enough how much I agree with your concerns. In our development process no file is committed to CVS without a comment of the form: [<bugzilla-id>] <the rest of the comment So for our development, it's not possible (not permitted) to simply commit code without a track record for it. From this we can automate a great many things. For example, we can query the CVS commits to know which bugs have been committed since the last build. These bugs can be listed as having gone into the build and can be marked as fixes for the reporters to verify. We also include a note in the bugzilla saying what build it's available in. This ensures we have accurate records for what we've done. When we make our plan, we open bugzillas for each and mark them. When we commit a contribution we include a stylized comment so that our IP log can automatically track them. Our entire process is geared around avoiding things we don't like to do and automating everything that's time consuming, error prone, and hence something we don't like to do. We don't like to work on the documents for the plans, we like to work on the items in the plan, so I don't want any heavy weight processes either. Lists of bugzillas an a little bit of organizational structure around that seems idea to me for that reason... And not that it's entirely relevant in this discussion, but we've even automated our plugin and feature version number checking so that if we commit a change to a maintenance stream and forget to increment the version of the plugin or the feature, the system tells us. We did this because it's incredibly error prone to do this correctly...
This blog illustrates now much clients appreciate good processes: http://eclipser-blog.blogspot.com/2008/01/do-bugs-go-to-heaven.html Consider that anyone can easily determine what's change: http://www.eclipse.org/modeling/emf/searchcvs.php?q=215260&project=0 which includes a delta view: http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.emf/org.eclipse.emf/plugins/org.eclipse.emf.edit/src/org/eclipse/emf/edit/provider/ItemProvider.java?root=Modeling_Project&r1=1.7&r2=1.8 Of course our release notes make these links available too. And of course we aren't perfect https://bugs.eclipse.org/bugs/show_bug.cgi?id=104005 Our plans tend to slip and to change. :-( Often that means a lot of good things that weren't originally promised get done though. ;-) I (or someone like Nick) should probably find some time to blog about this, since an improved planning process affects pretty much all committers and now is the best time to influence this is the direction we'd like to see it go...
(In reply to comment #8) > > Our plans tend to slip and to change. :-( Often that means a lot of good > things that weren't originally promised get done though. ;-) > Actually not a bad thing at all, just very agile. Plans are just that, a plan...but we all know they change. The key as you have stated Ed is to make sure that everything is in the plan, and it seems most developers don't mind adding it into bugzilla. The trick here is while eclipse seems to have a general structure for the joint releases (6 week iterations), there still needs to be some flexibility in how a group plans. Communication back to the community is very vital, but it only works well, if the community also has a say in what goes into a release. I have no problems with the big foundation members driving some of this and influencing it, but I also think in many projects there needs to be more visibility to what is being planned to be incorporated into a particular project. From that aspect I agree that everything should have a bugzilla entry before any work is started on including it into CVS. So I guess I'm all for the bugzilla idea, as long as it's consistently used.
A few thoughts... a) Hybridizing (1) and (2) can be done simply by sticking Bugzilla links (queries) in the strictly-formatted XML. b) Atom feeds would be cool: <entry><id>tag:projectName.componentName,2008:feeds-eclipse-plan-platforms-1.post-2008-01-11T00:00-05:00</id> <published>2008-01-11T00:00-05:00</published> <updated>2008-01-11T00:00-05:00</updated> <title type='text'>Supported Platforms</title> <content type='html'> ... html content ... </content> <author><name>bfreeman</name></author> <link rel='self' type='application/atom+xml' href="http://www.eclipse.org/projectName/feeds/plan-componentName.xml"/> <link rel='alternate' type='text/html' href='http://wiki.eclipse.org/projectName#plans'/> </entry> <entry><id>tag:projectName.componentName,2008:feeds-eclipse-plan-items-1.post-2008-01-11T00:00-05:00</id> <published>2008-01-11T00:00-05:00</published> <updated>2008-01-11T00:00-05:00</updated> <title type='text'>Plan Items</title> <content type='html'> ... html content (describing themes, plans, and links to bugzilla ... </content> <author><name>bfreeman</name></author> <link rel='self' type='application/atom+xml' href="http://www.eclipse.org/projectName/feeds/plan-componentName.xml"/> <link rel='alternate' type='text/html' href='http://wiki.eclipse.org/projectName#plans'/> </entry> (etc.) Of course this could be generated from simpler markup, such as: <plan> <release name="Project Name" version="3.4"/> <description> ... preamble blah blah ... </description> <platform type="secondary">win-win-64</platform> <platform type="primary">linux-gtk-32</platform> ... <item url="https://bugs...(query keyword/theme or in bug titles for 'faster')">Make It Faster</item> <item url="https://bugs...(query for component Zest)">Make it Zesty</item> <item url="https://bugs...(query for contributors from a given company/group)">Make It Zendy</item> ... <schedule date="2008-07-11T00:00-05:00" name="Release" type="firm"/> <schedule date="2008-01-11T00:00-05:00" name="Milestone 4" type="tentative"/> <deliverable url="http://path/to/deliverable/downloads/"> ... bit of fluff about zips </deliverable> <deliverable url="http://path/to/deliverable/updates/"> ... bit of fluff about update site(s) </deliverable> <deliverable url="http://path/to/Ganymede/updates/"> ... bit of fluff about being on the release train</deliverable> <compatibility url="http://path/to/compatibility/statement/or/migration/guide">3.3</compatibility> <nls url="http://path/to/statement about nls or link to Babel">English</nls> <nls url="http://path/to/statement about nls or link to Babel">French</nls> ... <appendix> ... yadda ... </appendix> </plan> Obviously a lot of those items are optional, including <platform> where if absent one would have to assume it's all cross-platform-compatible java. c) I did blog this -- recently in fact -- but more from the contributor side than the PMC/planning side: "You'd like another add-on? (feed a patch) Cause it's the finest in the nation? (feed a patch) Well there's no time left to add that When it's scope creep or it's plan ..." (http://divby0.blogspot.com/2008/01/time-for-m4.html) However, it's been a while since I've attempted to evangelize the wonders of Search CVS & a backing database for release notes & bug auditing. Raving about it in myriad bugzillae & the wiki [1] has been thus far ineffective (perhaps because there's a bit of setup required to adopt it?) [1]http://wiki.eclipse.org/Search_CVS, http://wiki.eclipse.org/Search_CVS%2C_Release_Notes%2C_Build_News Anyway, I'll write something one of these days, when I can come up with a good song to use as the inspiration. ;-)
Documentation on the new format: http://wiki.eclipse.org/Development_Resources/Project_Plan An example on display: http://www.eclipse.org/projects/project-plan.php?projectid=technology.dash
(In reply to comment #11) > Documentation on the new format: > http://wiki.eclipse.org/Development_Resources/Project_Plan > An example on display: > http://www.eclipse.org/projects/project-plan.php?projectid=technology.dash > I am concerned this could lead to too much "adminsitrivia" process. I think to get buy-in, and meaningful plans, there needs to be some slow rollout ... try-it-if-you-like-it approach. And see how those projects like it, what they learn from "the standard" approach. Then if it's successful, and handy, everyone will naturally want to migrate to it eventually. I'll also list a few implementation concerns: I don't think themes should be bugzilla keywords. Seems that would lead to an explosion of keywords. I don't think all requirements fit neatly into a theme, some are in none, some are in more than one, etc. So ... at least need "other" and let people define their own themes (which can't be easily done with bugzilla ... keywords are admin entered). I don't think the XML should accept any 'ol HTML. Perhaps the standard file needs to be strict XHTML (with CSS attributes defining secitons, on div's or headings) (which can still be parsed as XML), or if stays XML, then would prefer not to allow so much flexibility in sections like <introduction> ...html... </introduction> <release_deliverables> ...html... </release_deliverables> But instead limit it to text, with links to all the custom stuff? <introduction url="link to more info if desired"> ...text... </introduction> <release_deliverables url="link to more info if desired"> ...text... </release_deliverables> I say this because in my experience, once people start putting in their own HTML, the intended standard document get's very non-standard very quickly. I think the "bugzilla for every new feature" is a good idea, but ... again from experience ... these easily become meaningless, from a summary line anyway, depending on the level the new feature is described at ... could be "improve debugging" or could be "add remote step processing for x86 processor in mixed mode". Perhaps one way to improve the meaningfulness of these entries is to have some limit that "each project can only list the X most important features" where X is 3, or 5, or 10" (whatever number we agreed was reasonable). This limit could be adjusted, year to year, as experience was gained. After all ... if bugzilla was used, shouldn't have to list bugzilla's or items in this document at all ... people could do queries!. But, still might be nice to have "3 most important" in this document.
(In reply to comment #12) > I am concerned this could lead to too much "adminsitrivia" process. Could you expand on that a bit more? I'd like to avoid extra administrivia but at the same time, as Eclipse grows, we need a bit more standardization to make growth understandable and cost-effectively implementable. I tried to structure this proposal to be low overhead: if your project is already doing project plans, this shouldn't be extra effort. (Of course, if your project is not doing a project plan, then it will be more effort.) > .. will naturally want to migrate to it eventually. Unfortunately, not everything at Eclipse is "want-based" - some things are required. The IP process is required. And the Board has now said that standard project plans are required. What I'm working towards is the lowest overhead version of that. > I don't think themes should be bugzilla keywords. Seems that would lead to an > explosion of keywords. Well, if every project had different themes, then I can see that, but most of the keywords will be the themes from the Roadmap (plus "Other") - looking at history, the themes have been basically the same since the Foundation was formed. So I don't see the explosion of keywords problem. Of course, we could also just use [Theme Foo] style text in the bugzilla titles instead of keywords (but it would be slower for bugzilla to search). > I don't think all requirements fit neatly into a theme, some are in none, some > are in more than one, etc. So ... at least need "other" and let people define > their own themes Sure. You just say <theme name="Other"> > But instead limit it to text, with links to all the custom stuff? That makes it harder to archive the project plans (which is one of the goals of the Board) because then we have to spider all the "more info" links and archive all those pages and not spider too much, etc). > I say this because in my experience, once people start putting in their own > HTML, the intended standard document get's very non-standard very quickly. Yes, that's a problem. > I think the "bugzilla for every new feature" is a good idea, but ... > these easily become meaningless, from a summary line anyway, I'm not sure how to improve this - we can lead the horse to water, but we can't make her drink. In other words, we can define a project plan format, but we can't actually force projects to do good planning. However, if they do poor planning "improve stuff" then it will be obvious in the archived plans and roadmap. Perhaps peer pressure will improve the plans over time. I don't think that restricting it to three or five items is going to help that: people will put in "improve stuff" instead of something more precise and useful. Then there are those projects which will have hundreds or thousands of tiny bugs (instead of larger feature bugs) listed in their project plan. Again, I think our only practical solution is to try it and then use peer pressure to form a best practice for the size and shape of a project plan.
(In reply to comment #13) > also just use [Theme Foo] style text in the bugzilla titles instead of > keywords (but it would be slower for bugzilla to search). I'm not a bugzilla expert, but I could imagine that if there is a single keyword "plan" for those bugzilla items that are plan items, then there is no need to have separate keywords for the themes as well. So I'd guess that [Theme Foo] markup is fine from a performance point of view. If keywords are used, an admin needs to create any new keyword. Which may be an advantage to keep the list of themes synchronized between all projects; but I'd think that then some tooling is needed to ensure that the <theme Foo> markup in the project plan XML only allows valid Foo. > > I think the "bugzilla for every new feature" is a good idea, but ... > > these easily become meaningless, from a summary line anyway, What I've really learned to appreciate about the "bugzilla for every new feature" approach is that you can use the bugzilla "depends on..." field to associate the plan item with other smaller work items. You get an excellent view of progress, help for search and even hints for potential issues if problems are found after a feature is complete. What I'd love to see though is a little tooling to avoid the effort of entering each plan item twice (as bugzilla item and in the plan XML). I'd appreciate a tool to either (a) create new bugzilla bugs based on a project plan XML, or (b) create a template project plan XML based on a bugzilla query. Advantage of (b) is that there are automatic validation checks e.g. only valid keywords are possible.
I like Martin's idea of just marking things as plan items. I've always questioned this "theme" thing as something folks will pay lip service too because someone else decided the themes for them and now their plans need to be fit into a shoe they didn't help design. (In the past, someone has always told me "These are the themes." I don't expect that to change and hence I don't expect the themes to be all the useful for categorizing my plan.) The depends on thing is exactly how we've been associating fine grained plan items with the higher level plan items. I fully expect that Nick will produce a plan from a bugzilla query. I have no intention of trying to keep a plan document in sync with the actual mechanism I use for build and tracking my plan, i.e., bugzilla. It would seem best if the process were based on a bugzilla query rather than on maintaining this information manually.
The one problem I've seen with auto-generating a plan document out of bugzilla is that the "Description" field in bugzilla is fixed once a bug is created and cannot be changed afterwards. I've often run into the case where we've seen a plan item evolve over time such that we found additional aspect(s) that should be captured in the highlevel description, or just a better more concise description. In bugzilla, this is tracked in the comments (which are sometimes hard to follow if discussions get lengthy), therefore I'd probably generate the plan.xml only once and maintain it manually afterwards (except for addition / removal of plan items based on a new bugzilla query: in other words, I'd never update/merge a plan item from bugzilla into the plan.xml but I would add/remove items). Or does anybody know of a trick to update the bugzilla "description" field? That would be a helpful feature regardless of this plan discussion.
Martin, I wonder if the plan shouldn't just contain the Summary and any information about the description would be available only in the bugzilla. The extent to which this plan document requires manual intervention outside the conventional workflow that people actually use day-to-day (bugzilla), it will fail. I don't have time to keep two separate sources of information in sync... Maybe Nick has some good ideas.
(In reply to comment #16) > The one problem I've seen with auto-generating a plan document out of bugzilla > is that the "Description" field in bugzilla is fixed once a bug is created and > cannot be changed afterwards. So, instead of a static document, we could have a .php file that pulls the current .xml from bugzilla for all the bugs you need, and parses out the numbers and summary/descriptions. I already do this for Search CVS [1], and it updates the bugs and bugdescs tables [2] with changes in Bugzilla automatically every night. [1] http://wiki.eclipse.org/Search_CVS,_Release_Notes,_Build_News [2] http://build.eclipse.org/modeling/build/schema.php > Or does anybody know of a trick to update the bugzilla "description" field? > That would be a helpful feature regardless of this plan discussion. Have you tried just committing a change to the summary field in the bug? That's always worked for me (as recently as last night, in fact). Of course the other, perhaps simpler approach to have in a canned project plan is simply a link to a bugzilla query which contains all the relevant bugs for your project's release/milestone/branch. That way you can use Bugzilla to track your bugs and move them up/down the priority, rename them as required, and not have to regen the proj plan every time you want an updated list.
One thing I've been doing with XSL Tooling is following an approach that Scrum has, which is a product backlog. I've been using bugzilla to keep track of the product backlog (which I think most projects do, or should be doing at least). Anything that is planned to be worked on is entered as a bug or if a requirement is needed it's added as a bug. As was mentioned the depends on feature of bugzilla can be used to break down a large story (feature, theme, etc) into smaller stories (bugs/features) that will be worked on. It does take some due diligence on the part of all of the developers to make sure that items that will be worked on during the current milestone are marked using the target milestone. Anything targeted for the overall release is given a target version that covers that entire release, as it's actually planned. While I agree that there needs to be some overall goals associated with the plan. My fear is that the board is going to add more "traditional" style project management structure, which defeats the purpose of agile. Which is less useless paperwork that isn't maintained and is outdated (truthfully, what traditional project plan is ever accurate). A product backlog always shows whats being worked on, targeting particular bugs for particular milestones shows what is actually being worked on during that development iteration. What is missing is the concept of story points or something else that can show the average amount of work the team is getting done. The concepts I'm describing are best outlined in Mike Cohn's book, "Agile Estimating and Planning" http://herdingcats.typepad.com/my_weblog/2006/03/agile_estimatin.html. I agreee that planning needs to be done, but I think we can leverage the tools we have now, to have a good accurate plan, without necessarily inventing a new XML format to handle it. Getting the Bugzilla XML format and working with it should be good enough...you may need to add a few custom fields but it should be able to handle it from a developers stand point. Nick seems to have a similar approach to creating the project plan. Committers should be using the features in bugzilla to communicate what is actually being worked on, and yes I think everything (large to small) should be tracked in bugzilla. Too many things still show up that don't have a feature enhancement logged or a bug that tracked it.
(In reply to comment #19) > Committers > should be using the features in bugzilla to communicate what is actually being > worked on, and yes I think everything (large to small) should be tracked in > bugzilla. Too many things still show up that don't have a feature enhancement > logged or a bug that tracked it. +1 If you use Search CVS or Mylyn, the idea of "to every work item, there must first be a bug" is neither rocket science or crazytalk. Work items should be catalogued somewhere, and Bugzilla is IMHO the best approach given the tools we currently have, because that information can then be parsed umpteen different ways for umpteen different communities: * EMO/PMCs/PHBs: parse/digest xml into some other format [eg., a standard project plan], or load into a database * Developers: use Mylyn to track in Eclipse as queries / work items * Users/Developers: use Search CVS for public web UI for data mining of delta-to-file-to-bug mappings * Users: use Bugzilla's public web UI itself All that's required is a little retraining so that everyone uses the system the same way. Sure, it's easier to write code than to herd cats, erm, retrain developers, but ultimately it can be more effective.
+1 for supporting the plan.xml being based on bugzilla, but I don't think that projects should be forced doing so. If they want hand-written traditional plans that should be fine too, as long as the plan is in a machine digestible format (the scope of this bug). Also note that a project plan is more than just bugzilla/plan items. There's also constraints like planned compatibility, supported architectures, actual dates of the milestones, OS and execution environments, potentially server environments and compatibility with 3rd party drivers, downloadable artifacts and the like. Also, a particular sorting of the items that's hard to achieve in bugzilla might help making the plan more consumable to the public. To me, project plans are important in order to inform downstream consumers about what's going on in the project - which is a very important point in commercial adoption and thus community growth. Actually, I think the fact that we have a good culture at Eclipse about reliable planning and milestone trains is one of the facts that helps commercial consumption. That being said, I'm in favor of an XML format for the project plan that's not too hard to edit manually (ever manually edited an RSS feed?) but can be generated autmatically out of bugzilla. The RSS feed idea is cool to get informed about project plan changes (I really like this feature on the dev process, see http://eclipse-projects.blogspot.com/2008/01/monitoring-changes-to-development.html but the corresponding markup should be optional to allow for easy manual editing for those who don't need it. I'd probably be generating the plan once and maintain it manually afterwards; Others might always generate it out of bugzilla alone based on some fixed template; yet others might always edit it manually only. All these use cases should be supported by the proposed format. Regarding bugzilla descriptions to be editable, I just filed bug 224118 requesting this feature (but it might take a while till we get it since it's a known enhancement request at bugzilla.org that's only partially implemented for now - see the bug for more details).
(In reply to comment #21) > Also note that a project plan is more than just bugzilla/plan items. There's > also constraints like planned compatibility, supported architectures, actual > dates of the milestones, OS and execution environments, potentially server > environments and compatibility with 3rd party drivers, downloadable artifacts > and the like. Also, a particular sorting of the items that's hard to achieve in > bugzilla might help making the plan more consumable to the public. Well, for a Eclipse project most of what you mentioned is already outlined. We already have the set dates, we know what the iterations are, we know which OS environments we need to support. Server environments, etc can be documented as Bugzilla features, compatibility is a feature in bugzilla and a testing task that needs to be done. Downloadable artificats, are the results of the milestones and setting that up and tracked is a bugzilla feature/task entry. It's all in how you work the backlog. The issue I think we are still running into is the still the transition from tradition project management philosophies and Agile project management philosophies. A good overview of the Product Backlog type management that Ed, Nick, and I have been advocating can be found in this article. http://www.mountaingoatsoftware.com/product_backlog I would hope that our Product Owner would be the eclipse member companies and the user community as a whole in order to help us determine what should be done each milestone, and what the overall priority is. In some projects this may not work well...so somebody or a group of people will need to act as the product owners. Programmers like things simple and doesn't get in our way of getting done what needs to be done. I don't want to see this become an "Office Space" version of TPS reports. > > To me, project plans are important in order to inform downstream consumers > about what's going on in the project - which is a very important point in > commercial adoption and thus community growth. Actually, I think the fact that > we have a good culture at Eclipse about reliable planning and milestone trains > is one of the facts that helps commercial consumption. And this information can be conveyed out of bugzilla. It just takes formatting the information differently depending on the user that is seeing it. I'd personally like to just see a backlog of of items that are scoped for say 3.4, then to see all backlog items that are out there....but I also want to see what didn't make it so I can raise the issue that it should be included in future backlog items. > > That being said, I'm in favor of an XML format for the project plan that's not > too hard to edit manually (ever manually edited an RSS feed?) but can be > generated autmatically out of bugzilla. The RSS feed idea is cool to get > informed about project plan changes (I really like this feature on the dev > process, see You could use an XSLT to generate a Docbook or DITA version of the project plan. There are standard tools and schemas available to allow manual editing of those XML formats. Anyways, we need to keep the burden of maintenance on these plans to a minimum, otherwise the best intentions aren't going to be done. I agree that plans are important for communication, but they need to be low maintenance, and ideally generated from the existing bugzilla data if at all possible, with some supplements from static files that don't or hardly ever change. A plan that is only updated every six months is worthless...to many requirements have changed, a plan that is updated every 6 weeks with what has been done, and what is planned for the next 6 weeks...that is more relevant. Bugzilla provides us with that ability through it's xml reporting.
Martin, David, Have you tried converting your current project plans to my proposed XML format from comment #11 ? I tried to include all the features that you have been (post facto) asking for, so I'd really appreciate feedback from you on what is or is not working. Ed, Nick, Same question plus the way the project plan php page I built works is exactly what you are talking about: it gathers the descriptions, etc, from the specified bugzillas. So you only need to enter the information in one place. Or maybe I'm missing something in your comments? Dave, David, Please note that you have six board members who should be representing your interests (the five committer reps and the IBM rep). That's a solid 1/5th of the members. If you believe the Board is defining policies that are counter-productive, you should talk directly to those six people. I'm not a member of the Board and I don't attend the Board meetings, so talking to me (e.g. on this bug) about Board policies is a lot less effectively than talking to them directly.
(In reply to comment #23) > > Dave, David, > Please note that you have six board members who should be representing your > interests (the five committer reps and the IBM rep). That's a solid 1/5th of the > members. If you believe the Board is defining policies that are > counter-productive, you should talk directly to those six people. I'm not a > member of the Board and I don't attend the Board meetings, so talking to me > (e.g. on this bug) about Board policies is a lot less effectively than talking > to them directly. Already have done so, in fact I blogged about it and I know at least two of them are CC'd on this bug. I'll just summarize my feelings with the Agile Manifesto. Individuals and interactions over processes and tools Working software over comprehensive documentation Customer collaboration over contract negotiation Responding to change over following a plan That is, while there is value in the items on the right, we value the items on the left more. This doesn't mean I don't think some sort of plan is necessary, or that documentation isn't necessary. I just don't want the process to get too heavy weighted which is my concern when we start to talk plans. One last thing, is there an XML Schema for that XML file? The reason I ask, is that if there is a DTD or XML Schema, then an XML Editor can be used to help edit the file and maintain it better, Plus validation against the XML file can be done to make sure that it is in the correct format.
(In reply to comment #24) > I just don't want the process to get too heavy > weighted which is my concern when we start to talk plans. My point is that this bug is not about whether to have XML format plans - the Board has already decided that and told me to implement it. This bug is about what the XML format plans should contain. If you want to argue about "whether", you'll need to use a different channel.
(In reply to comment #25) > My point is that this bug is not about whether to have XML format plans - the > Board has already decided that and told me to implement it. This bug is about > what the XML format plans should contain. If you want to argue about "whether", > you'll need to use a different channel. > No problem. Is there a xml schema for this to help with editing of this project plan?
I think we've pretty much touched on all the issues and we need a guinea pig to flesh out what appears to be a pretty reasonable skeleton/proposal. I'd like to volunteer Nick to be the guinea pig. This way we can have something complete and concrete for others to critique and to help improve. :-P I'm a bit concerned about time lines right now though, with the release quickly drawing to an end. Likely very few people have spare cycles these days which is bound to get worse as we lead up to the end of June. Perhaps the target for completion should be looking toward the start of the next planning cycle after the current release completes.
(In reply to comment #27) > I'm a bit concerned about time lines right now though, Ed, you're on the Board. You were at the March 17th Board meeting where the Board said "have a draft of the Roadmap by the end of June" and that a draft of the Roadmap includes "projects plans written by the project teams in standard XML format". Hence the XML format must be defined soon (this month) so that projects have a chance to find time to convert their plans. If you thought the schedule was incorrect, why didn't you say something at the Board meeting?
It seems to me that I've never seen a plan from the platform team until well past September. I'm doubtful that anyone will be drafting a plan for the next release until they finish this release. I know that with my own tiny team, I just don't have the capacity to plan for the next release while scrambling to finish the current one. So while Nick might be able to help with the infrastructure and design of this new planning process, his priorities will be getting build done to ensure that Ganymede is successful. To take a step back, I'd say that the whole top-down road map process seems to be flawed to begin with. A plan ought to be the sum total of what each individual project/component is doing. I made that very clear back at the December board meeting. It's pointless for someone to tell me the themes and them have to shoehorn my actual work items into those. In any case, the board is quite used to things not working out the way they might decree; I don't actually recall a directive from the board mandating a roadmap for the end of June; I definitely would have objected to such timing. The board directed the foundation to work on a common build infrastructure as well, but that's made no progress either, so I'm sure the board won't be shocked to find no one has time to plan for the next release while they are busy making the current one successful. I'll be there to explain it to them in person should there be any confusion. In the end, the most important thing is that we arrive at a sensible process that people will actually use and want to use. I'll be sure to raise this whole issue at our next board meeting. We can also discuss this issue when the committer representatives meet with you before the board meeting.
I want to be sure that Mik and Doug are aware of this discussion. Perhaps they'll recall specific discussions around the roadmap timing better than me.
(In reply to comment #29) > To take a step back, I'd say that the whole top-down road map process seems to > be flawed to begin with. A plan ought ... It's pointless for ... Ed, like I said in comment #25, this bug is about the file format, not about the policy. I don't have the luxury of ignoring instructions from the Board. > I don't actually recall a directive from the board mandating a > roadmap for the end of June; I definitely would have objected to such timing. I don't feel right posting the slides that I presented to the Board on this bug because that's a Board thing, but the quotes in comment #28 are straight from those slides and you all nodded/voted for them.
Bjorn, The issue is to what extent the things we come up with in this bugzilla are etched in stone and to what extent it can evolve as folks adopt it. I'd suggest we'd best be flexible so that we can involve a community that's likely to pay no attention to this until they realize there's a new set of rules for them to follow. Yes, I know this must be incredibly annoying and frustrating to you (only 20 of the impacted 1000 people are paying attention), but everyone on this bugzilla is effectively saying the same thing: this needs to be flexible, and it's not entirely clear that all this new stuff is goodness until we take it for a test run...
(In reply to comment #32) Maybe I haven't been clear enough: I'm 100% for flexible and agile - consider the evolution of the Board-required standard project information effort: it evolved from a required home page format to a required left menu format to a single required "Information about xxx" to a single required "About this project" - in each case due to feedback from the projects and with as much backward compatibility as I could implement. I expect the same thing to happen here. But we need a starting point, thus the XML format that I've proposed in this bug. Improvements are always welcome as long as it doesn't end up "everyone does their own thing". In order to produce the Roadmap we need some machine-readable project plan format. I really don't care what it is as long as it is machine-readable and consistent across all the projects. I made this current proposal based on analyzing the existing project plans and the discussions that we all have had over the last couple years.
Created attachment 95007 [details] XSD for Project Plan Here is an XSD, that mirrors the content in the proposed XML file format. There are a few changes. 1. The Project plan elements are put into a namespace called: http://www.eclipse.org/projectplan 2. The HTML content examples, have been setup for xsd:any content. Meaning that wrapping the information in CDATA is not necessary as long as XHTML is being included. 3. Min and Max Occurs for elements are enforced. It took best guesses at what should be in there. There are some concerns about the design and future extensibility. I work for an XML Standards organization, and from experience for extensibility of elements, it's better to use Elements instead of attributes. It allows greater freedom to extend the XML and keep compatibility. As was previously mentioned by others in this thread, allowing free formed HTML may not necessarily be the best thing. It allows too much ambiguity in the presentation. I would suggest leveraging Docbook which is designed for technical specfication writing, and separates the presentation from the content. This XML should only have content not presentation. Leave that to the Stylesheet that renders it. Anyways, I'll attach as well a sample XML that validates against the schema. Having the schema will help ensure that manual as well as programatic generation of the XML is valid, so that you aren't having to process and deal with invalid XML. This XML was generated using the Eclipse Webtools editors and plugins.
Created attachment 95008 [details] Sample XML that validates against XSD.
Note that the xsi:types should be removed. It's not recommended or a best practice to have them in the xml, it acts as override. Anyways, hope this is helpful.
As I've been volunteered (thanks, Ed!), I'll take some time to adopt this format for our plans, and see if it works for our needs. However, some implementation details are missing from comment 11. a) Where is the source XML for http://www.eclipse.org/projects/project-plan.php?projectid=technology.dash ? I need a working sample XML file from which to work. b) Where does this XML file need to be put in CVS so that http://www.eclipse.org/projects/project-plan.php?projectid= can find & render it? Are you expecting a standard path/location (bad), or are you referencing it based on its path/filename as linked in some field in the portal-based metadata (good)? c) Thanks to Dave for the XSD & sample XML data. Bjorn, are these in fact correct based on your design intent, and do they conform to the Dash sample data?
(In reply to comment #37) > a) Where is the source XML? Found it: http://www.eclipse.org/dash/project-info/plan.xml > b) Where does this XML file need to be put in CVS? Found this too -- uses the portal's project plan url field.
Created attachment 95055 [details] Tweaked to allow Either Namespaced or no namespace elements This tweaks the XSD to allow either namespace or no namespace elements in the User Areas. I'll also upload a sample plan with Docbook markup in it to show how that can be used to help separate content from presentation.
Created attachment 95057 [details] Plan with Docbook markup in User Areas This plan shows how Docbook could be used in place of HTML to help separate content from presentation, and allow for a more unified consistent look and feel. The stylesheet would control the final formatting.
I'd argue that this bug is suggesting something different (and bigger) than the board's discussion around XML formats. Not that there is anything wrong with that. I think this bugzilla opens up a good idea and I would love to see a few projects being trailblazers and moving over to harvestable bugzillas and transparent detailed plans in a standardized XML format (and getting the kinks out of the process). I don't see anything in the board minutes indicating a decision to move the low level detail of planning over to an XML format like this in the near term. Does anyone have a pointer? This proposal seems to be somewhat more heavyweight than is required to satisfy the "Roadmap Discussion" section of http://www.eclipse.org/org/foundation/boardminutes/2007_12_12-13_Minutes.php. If I read the board summary correctly, all that is really needed from each project is an XML file describing what the project is doing for each Eclipse theme to facilitate autogeneration of roadmap document (e.g., http://www.eclipse.org/org/councils/roadmap_v3_0/.). One reading of the minutes would indicate that something like the following would be sufficient for that need. <project x> <theme y> Text from project X about what they're going to do around theme Y </theme> </project> Thx, Chris
(In reply to comment #41) > I'd argue that this bug is suggesting something > different (and bigger) than the > board's discussion around XML formats. Really? That wasn't my intent. > I don't see anything in the board minutes You'll have to talk to Mike about the Board minutes and copies of the presentations. > One reading of the minutes would indicate that something like the following > would be sufficient for that need. If that's all that's required, it would certainly be easier. Of course, as a separate document, it's highly unlikely to be up-to-date or even (for many projects) to exist at all. I'm guessing that the fewer files a project has to maintain, the happier everyone will be with the accuracy of the data.
Man, it's like getting to a party late only to find the keg has been drained! I'm afraid my notes from the board meeting are too cryptic, but I can confirm that the board is looking for a draft roadmap by the end of June, a frozen version by the end of August, and approval by the Sept board meeting. The roadmap is part of the bylaws, so while we may or may not like it, it's something we have to do. The plans are something we're supposed to do for our projects. I'm all for finding a way to automatically generate the roadmap from the plans as a way to simplify this process. Bjorn has made it clear that the XML format is up to us to define and experiment with. The board couldn't care less what that format looks like. Anyway, I like the "easy to generate" from bugzilla approach, as most everyone else here has already said. I'm sure I'll be hand-editing some of the plan, too, as Martin points out.
Doug, One thing that I find confusing is I don't believe the platform ever had a plan until well into September or even later. I can't imagine having a plan ready for EMF until well into summer. I think in the past the roadmap was some kind of motherhood and apple pie vague document produced by the requirements council that everyone paid lip service to much later because it was required. I thought we were moving towards more of a bottom up thing where the full plan really crystallized out of the sub plans. But I don't think it's been well communicated to the community that they are expected to have plans by the end of June. I don't think that will go over well... I'm hoping that the process and formats will remain flexible as we explore it during the upcoming release cycle. I'd like to talk to the board at our next meeting about the schedule and timing for this transition...
(In reply to comment #43) > Bjorn has made it clear that the XML format is up to us to define and > experiment with. The board couldn't care less what that format looks like. > > Anyway, I like the "easy to generate" from bugzilla approach, as most everyone > else here has already said. I'm sure I'll be hand-editing some of the plan, > too, as Martin points out. I'm going to stick to the topic of the XML format here. Again I'll say that presentation and content need to be separated and the stylesheet needs to handle this. To handle the manual editing portions, I'll make recommendation of using the Xinclude specification to help manage and merge these pieces back into one complete XML project plan document. <preamble> <xi:include href="someplace where the xml to be included is stored"/> </preamble> This allows the manual portions to be maintained outside of the portions that are automatically generated. To help with the merging and xinclude support itself, we have this built into the XSL Tooling project, and include an Ant Task for the xinclude merge, that will generate the combined xml. Just something to think about.
(In reply to comment #45) > This allows the manual portions to be maintained outside of the portions that > are automatically generated. What parts of the XML are automatically generated? In my proposal (fading into the past), there was nothing that was automatically generated: the project teams authored the whole XML document. Yes, the XML document had some sections that referred to bugzilla queries, but those queries did not alter the XML file itself. What am I missing?
comment #44 Ed, you're right. It really is late August or early September before plans start shaping up. And here I was starting at my own Ganymede++ schedule as I wrote my last comment! The situation is even worse, though. Normally the roadmaps are ratified around EclipseCon, at least if you look at the last two. http://www.eclipse.org/org/councils/roadmap_v2_0/index.php http://www.eclipse.org/org/councils/roadmap_v3_0/index.php I'm coming to the board late here, so I don't know what was previously discussed around our current (lack of) roadmap, but apparently we're behind schedule? Anyway, this move to generate the roadmap from actual plans is a recognition of how things are actually done bottom up, as you point out. So that's good. I guess the timeline is problematic. Perhaps Bjorn or Mike could weigh in on the dates. Experimenting with the format now is good, but perhaps the Committer Reps need to go back to the Board and indicate that it will be around M1 before the plans and the roadmap are generated. Further, whereas roadmaps were once static, they will now be dynamic documents, which change as the project plans themselves change. (Plans never lose any items; some items just get deferred and new ones are added.) This is good news, but I wonder if the Board realizes this. Well, it looks like we have an action item for the April meeting. Anyway, I think we have to support Bjorn on vetting the format. The dates are our problem to deal with on the board.
(In reply to comment #47) > Further, whereas roadmaps were once static, they will now be dynamic documents, > which change as the project plans themselves change. The Roadmap will be a frozen-in-time copy of the plans as of some date. I will write code that does that. The date will be some date in advance of when the Board needs to approve the Roadmap (a month? six weeks?).
Frozen in time make sense, but it would sure be interesting to grab a snapshot at the end and compare how closely the final deliveries matched the roadmap. Maybe I'm just stirring up trouble, though. :)
(In reply to comment #46) > (In reply to comment #45) > > This allows the manual portions to be maintained outside of the portions that > > are automatically generated. > > What parts of the XML are automatically generated? In my proposal (fading into > the past), there was nothing that was automatically generated: the project > teams authored the whole XML document. Yes, the XML document had some sections > that referred to bugzilla queries, but those queries did not alter the XML file > itself. > > What am I missing? Depending on how much automation you want to have, many of the areas could be automatically generated from the various bugzilla queries that have been suggested here, since bugzilla itself can return XML pieces that could be transformed into the necessary pieces. depending on level of detail, the individual milestone sections could be generated based off bugzilla queries for the project. Information on the release, project id, and version can all be generated from bugzilla as well. I think I do have a potential issue with the way the internationalization section is done. Is it the intent to have projects maintain multiple languages. Also, I think there needs to be an identifier for the internationalization if it is to be in multiple lanaguages. Adding the xml:lang="en-US" or similar standard attribute would help in displaying the appropriate information. We really need to make maintaining the xml down to the minimum that a person has to do manually themselves. Somebody that may be a project manager on multiple eclipse projects isn't going to want to hand craft the plan.xml for each of their project. Creating and maintaining small portions like the docbook sections wouldn't be too much work. I'm looking at this from my point of view where I have project management responsibilities on my project, but also still have coding duties that need to get done as well, and a day job that has to be done (I'm not fulltime on eclipse). So the more automated from my standpoint the better.
(In reply to comment #41) > I'd argue that this bug is suggesting something different (and bigger) than the > board's discussion around XML formats. > ... > > One reading of the minutes would indicate that something like the following > would be sufficient for that need. > > <project x> > <theme y> > Text from project X about what they're going to do around theme Y > </theme> > </project> > Thanks to that link to the minutes. Just to illustrate how diversity works :) even though I might be in the minority, I'll say there's some attractive aspects to this simpler approach. I haven't thought it trough completely, but seems it would be a smaller step, individual projects could implement a richer system if they wanted, but others could whip up a quick document if they'd prefer. It also, seems to me to better capture the spirit of "road map" .... an early, high level look at what might possibly be coming, instead of the detailed, dynamic, tracked-plan that seem to have creeped into some comments in this bug :) And, while the early date is way too early to have a good detailed plan ... maybe that's best for a road map, as then it's done quickly, and is over with. :) Not to mention, at least gives some high level idea of what's being considered (which is more of a software 'road map', in my mind). Also, it seems to better leave open the possibility that new themes could be introduced by some projects, as they saw fit. I'll admit, though I'm still pretty confused by what's needed here and by whom ... guess you would have had to have been there and heard that discussion ... so, take my comments as just observations (not criticism nor position).
(In reply to comment #43) > Anyway, I like the "easy to generate" from bugzilla approach, as most everyone > else here has already said. I'm sure I'll be hand-editing some of the plan, > too, as Martin points out. I'm catching up on things also. +1 for using bugzilla as much as possible to generate the plan... by searching keywords.. milestone dates... etc... In PDE, we try to take advantage of keywords like 'noteworthy' and milestone dates to keep people in check of what is actually done. The cool thing about this is that plans would be "living" which reflects reality more... The crappy part is getting people to adopt to this bugzilla 'workflow' ... but it may have better potential than the nag notes to update the project-info.xml :)
(In reply to comment #51) > Just to illustrate how diversity works :) even though I might be in the > minority, I'll say there's some attractive aspects to this simpler approach. I > haven't thought it trough completely, but seems it would be a smaller step, > individual projects could implement a richer system if they wanted, but others > could whip up a quick document if they'd prefer. It also, seems to me to better > capture the spirit of "road map" .... an early, high level look at what might > possibly be coming, instead of the detailed, dynamic, tracked-plan that seem to > have creeped into some comments in this bug :) I would actually vote for looking in this direction as well. It's good to reflect live updates of project plans in collective Eclipse plans but not necessarily all the bug-level details.
+1 for a standardized plan format as long as it leaves flexibility for manually controlling the content of some sections (e.g. intro) and inserting custom HTML (e.g. images). Also +1 for a Bugzilla-driven plan. On Mylyn we've been thinking about using the "plan" keyword for plan-level bugs and using dependent bugs for the actual works, since all of our planning comes from Bugzilla as well. Some Mozilla projects take a similar approach. Fyi, if anyone want a Java API for accessing Bugzilla programatically you can get it from org.eclipse.mylyn.bugzilla.core. On the Architecture Council call Ed Merks raised a concern that the proposed timing was problematic because it had projects come up with plans while they were trying to wrap up Ganymede. This would be a problem on Mylyn as well and all that I can imagine us doing a good job on in the June timeframe is a boilerplate plan. We don't start our planning cycle for the next release cycle until July. I wonder if it would make sense to have a couple of projects try out the standardized facility in the June timeframe before moving everyone to it later in the summer?
(In reply to comment #54) > On the Architecture Council call Ed Merks raised a concern that the proposed > timing was problematic because it had projects come up with plans while they > were trying to wrap up Ganymede. This bug (215301) is about the file format. This bug is not about schedules. If you want to talk about the schedule for the Roadmap, please do so on another bug.
(In reply to comment #50) > I think I do have a potential issue with the way the internationalization > section is done. Is it the intent to have projects maintain multiple > languages. Also, I think there needs to be an identifier for the > internationalization if it is to be in multiple lanaguages. Adding the > xml:lang="en-US" or similar standard attribute would help in displaying the > appropriate information. Dave, Could you suggest an improvement here? I just took what I saw in existing project plans and made a section for it. Are you suggesting something more structured? (In reply to comment #51) > Also, it seems to better leave open the possibility that new themes could be > introduced by some projects, as they saw fit. David, Nothing in this proposal prevents projects from adding new themes. I'm not sure where you saw that restriction. The themes are just text and you can enter whatever text you want.
(In reply to comment #56) > (In reply to comment #50) > > I think I do have a potential issue with the way the internationalization > > section is done. Is it the intent to have projects maintain multiple > > languages. Also, I think there needs to be an identifier for the > > internationalization if it is to be in multiple lanaguages. Adding the > > xml:lang="en-US" or similar standard attribute would help in displaying the > > appropriate information. > > Dave, > Could you suggest an improvement here? I just took what I saw in existing > project plans and made a section for it. Are you suggesting something more > structured? What is the the intent of this section? Is it to provide the plan in multiple languages. It's hard to tell what the intent is purely by the tag name, and how it occurs. I can provide a better answer once the intent question is answered.
(In reply to comment #57) > What is the the intent of this section? See http://www.eclipsecon.com/eclipse/development/eclipse_project_plan_3_3.html the section named "internationalization" - that was the intent of the <internationalization> section.
(In reply to comment #58) > (In reply to comment #57) > > What is the the intent of this section? > > See http://www.eclipsecon.com/eclipse/development/eclipse_project_plan_3_3.html > the section named "internationalization" - that was the intent of the > <internationalization> section. > Okay, so this is more about NationalLanguageSupport?
(In reply to comment #59) > Okay, so this is more about NationalLanguageSupport? Well, no, it is much simpler than that: I saw that most project plans included a section named "Internationalization", so I included a section named <internationalization>.
(In reply to comment #37) > a) Where is the source XML for ... Good suggestion: the project plan displayer page (http://www.eclipse.org/projects/project-plan.php?projectid=technology.dash) now has a "view raw xml" link at the bottom right. > b) Where does this XML file need to be put in CVS so that ... Another good suggestion: the view raw xml now provides that information as does the project meta-data documentation page. (In reply to comment #39) > ... XSD ... I admit my total ignorance of XML Schemas. We all have weaknesses, and this is one of mine - I've always written all my XML by hand. I do not know how to write them, how to reference them in the XML file (does one?), or how to test them. I would be happy to have a copy of an XSD in the CVS tree and reference it from the documentation, but I'm going to have to defer to one of you to update the attachment and verify that it matches the example (http://www.eclipse.org/projects/project-plan.php?projectid=technology.dash&raw=1) (In reply to comment #40) > ... Docbook ... Given the firestorm that I ignited by taking the committer reps suggestion of using bugzilla as the planning mechanism - a firestorm of objection that this was "heavy handed" and "not justified" and etc., I think it would be unwise to insist on Docbook. (In reply to comment #45) > ... xinclude ... Happy to include it. The source code for the displayer page is at /cvsroot/org.eclipse/www/projects/project-plan.php. Attach a patch here that supports xinclude and I'll apply it. (In reply to comment #51) > ... guess you would have had to have been there and heard that discussion ...\ Given that the posting of the Board minutes is always very delayed and that I'm not in a position of sufficient authority to post them, yes, you would have had to be there. Or you would have to trust your committer board reps to be looking out for you. I had a long (for me) call with them on Monday discussing this issue and I'm comfortable that the current proposal reflects their opinions as well as that of the rest of the Board. (In reply to comment #52) > The crappy part is getting people to adopt to this bugzilla 'workflow' ... Never one to be accused of not listening and being agile, I've modified the proposed format to make the bugzilla portion optional. Now it encourages the use of bugzilla for planning, but if projects want to just write html paragraphs describing their planned items, that is also supported. See the example (http://www.eclipse.org/projects/project-plan.php?projectid=technology.dash "Appealing to the Broader Community"/Proposed) and the wiki (http://wiki.eclipse.org/Development_Resources/Project_Plan)
(In reply to comment #60) > (In reply to comment #59) > > Okay, so this is more about NationalLanguageSupport? > > Well, no, it is much simpler than that: I saw that most project plans included > a section named "Internationalization", so I included a section named > <internationalization>. Well, I think we need to define this a bit more...what type of internationalization information is to be included. Right now it's just free form, and personally I think there is too much free form XHTML/HTML information included. I like to be as specific as possible and leave it to the XSL to render it in a human readable format. > > > (In reply to comment #39) > > ... XSD ... > > I admit my total ignorance of XML Schemas. We all have weaknesses, and this is > one of mine - I've always written all my XML by hand. I do not know how to > write them, how to reference them in the XML file (does one?), or how to test > them. I would be happy to have a copy of an XSD in the CVS tree and reference > it from the documentation, but I'm going to have to defer to one of you to > update the attachment and verify that it matches the example > (http://www.eclipse.org/projects/project-plan.php?projectid=technology.dash&raw=1) > > (In reply to comment #40) > > ... Docbook ... > > Given the firestorm that I ignited by taking the committer reps suggestion of > using bugzilla as the planning mechanism - a firestorm of objection that this > was "heavy handed" and "not justified" and etc., I think it would be unwise to > insist on Docbook. > For both the XSD and the Docbook examples see the attachments. The problem with HTML is that it isn't well formed and mixes presentation and content together, not giving you much control on a standard look. I would at least recommend making it XHTML content at the minimum if you don't want to go the docbook route, but you get more control over the look and feel and a standard look and feel is always a good thing. If they have the XSD, and add it to the XML Catalog for Web Tools, then they will get content assistance. You can also setup validation to happen before you even process the XML file to make sure that it is at least valid according to the XSD. I've already attached some examples to this bug. > (In reply to comment #45) > > ... xinclude ... > > Happy to include it. The source code for the displayer page is at > /cvsroot/org.eclipse/www/projects/project-plan.php. Attach a patch here that > supports xinclude and I'll apply it. A simple Xinclude is something like this: <xi:include href="locationtoxmlfiletoinclude"/> So if somebody wanted to include a portion of XHTML and had it stored somewhere like the wiki, then you could do somehthing like: <xi:include href="http://wiki.eclipse.org/someproject/header.xml"/> You would just need to copy that information in from the site using your XSLT and document() function to bring in the information.
(In reply to comment #62) > Well, I think we need to define this a bit more...what type of > internationalization information is to be included. Sure - suggest some words to add. > personally I think there is too much free form XHTML/HTML information > included. Yes, I heard you on that, but I'm not going to change that (yet) due to my "pick ones battles carefully" philosophy. Given the firestorm around using bugzilla items for planning (I thought it was a no brainer, but boy was I wrong), I think that structured text is not worth fighting for this year. > For both the XSD and the Docbook examples see the attachments. > I've already attached some examples to this bug. I updated the example and thus the XSD you attached previous is out of date. I look forward to a revised file. > I would at least > recommend making it XHTML content at the minimum That sounds reasonable - what do I need to do differently? > A simple Xinclude is something like this: > You would just need to copy that information in from the site using your XSLT The code doesn't use XSLT. Again, feel free to offer a patch (/cvsroot/org.eclipse/www/projects/project-plan.php)
(In reply to comment #63) > > For both the XSD and the Docbook examples see the attachments. > > I've already attached some examples to this bug. > > I updated the example and thus the XSD you attached previous is out of date. I > look forward to a revised file. > > > I would at least > > recommend making it XHTML content at the minimum > > That sounds reasonable - what do I need to do differently? Well, I can enforce this by making sure in the XSD that it only allows information from the XHTML namespace in those free form sections. So that will at least check to make sure that information setup correctly. > > > A simple Xinclude is something like this: > > You would just need to copy that information in from the site using your XSLT > > The code doesn't use XSLT. Again, feel free to offer a patch > (/cvsroot/org.eclipse/www/projects/project-plan.php) > Okay, I'll take a look and see what you have. The original example you had, had a stylesheet that was transforming the XML. So I'll take a look at the current project-plan.php and see what it looks like.
(In reply to comment #64) > Okay, I'll take a look and see what you have. The original example you had, > had a stylesheet that was transforming the XML. Ah, sorry I was confusing about that: the stylesheet just takes the XML and shows a human readable version of "don't look here, look over there" so that when an outside goes to the xml file and see confusing xml, they don't freak out and give up. The actual semantic processing is done by the project-plan.php code, and the "look over there" text points to the project-plan.php page. Take a look at: http://www.eclipse.org/dash/project-info/plan.xml and you'll see what I mean.
Bjorn, For the XML Schema, is there some scope to standardize how environment and dependency/reference stack information is represented in the XML version of the plan? Perhaps in addition to freeform HTML. You can see the sort of information we use in the BIRT Plan here: http://www.eclipse.org/birt/phoenix/project/project_plan_R2_3_0.php. And if I recall correctly we modelled that after an original Platform Plan. If all projects conveyed their environment information in a machine parsable way, that gives some scope for reporting to the community what a "standard" supported environment is for Ganymede for example. It may also help us collectively identify mismatches where a set of dependent or inter-related projects do not support a common set of environments. Paul.
Hi Paul, this sounds like an excellent idea, (and I'd likely be using it for our project), but I think it's important to also allow for smaller projects to not fill in that kind of information. Or probably add it in a later iteration of the plan schema and leave it freeform for now?
(In reply to comment #66) > For the XML Schema, is there some scope to standardize how environment and > dependency/reference stack information is represented in the XML version of the > plan? Perhaps in addition to freeform HTML. Feel free to suggest something as starter for the discussion...
The discussion seems to concluded and the issues brought up resolved, i.e., 1. projects can use bugzilla or not - both mechanisms are supported 2. the timing of the requirement is not part of this bug - talk to your committer Board reps about timing 3. projects can be as agile as they want: this is definition of machine-readable project plan format - how projects execute against their plans is up to them 4. this is a first version - all committers and project leads are encouraged to help improve the format. For example, comment #40 and comment #66. I am going to mark this bug as RESOLVED in that we (I?) have defined an initial XML format for project plans and implemented the (initial) tooling to support that format. Projects are encouraged to convert their plans to this format and to help revise/improve this format when they see problems.
Released or close for STAGING_212. Please see actual comments and original closure status of this bug. This message does not imply any action taken beyond those already described.
Bjorn is the latest XML format on the Wiki page, if so I'll see about getting the XSD updated accordingly. Ideally, the XSD would be the driver, and the XML comes from the XSD. That way they are always in synch.
(In reply to comment #71) > Bjorn is the latest XML format on the Wiki page Yes, thanks for checking.
Hi, Bjorn, I hope this is still a good place to ask questions and discuss the new XML project-plan format. I only recently came across this, on finding Rich's e-mail about the GMF 2.2 plan. I have drafted an OCL 1.3/2.0 plan in this new XML format: http://dev.eclipse.org/viewcvs/index.cgi/www/modeling/mdt/ocl/project-info/plan.xml?root=Eclipse_Website&content-type=text%2Fplain&view=co Unfortunately, as the components of the MDT project are not (yet) recognized by the Eclipse Foundation as projects, this plan document isn't particularly consumable: the XSLT simply shows a link to the project-plan PHP script. However, as MDT OCL isn't a project and doesn't have the meta-data required to drive the Foundation's common web interfaces, this just doesn't work. I don't see, either, how the MDT project plan will aggregate its components' plans into its XML plan document, unless perhaps it maps components to Themes. That doesn't seem right, though. Could we either: (a) Enhance the plan schema to support nesting the <plan> element (as different MDT components have different release numbers, and +n schedules in Galileo) (b) Enhance the XSLT to actually render the contents of the plan instead of requiring the PHP script (c) Add modeling.mdt.ocl to the database that controls all of the web UI driven by the Project Meta-data, so that the PHP script will recognize it (once I have filled in the meta-data) I'm open to other suggestions, too, of course. The problem is, that the MDT project will not be able to publish its plan in the current format, because MDT as such is simply an umbrella over independent components. There are no MDT deliverables to plan. Other modeling projects will be in the same situation: EMFT, GMT, M2T, and M2M, to name a few.
Christian, I think what you need is bug 238434
(In reply to comment #73) > However, as MDT OCL isn't a project and doesn't have the meta-data required to > drive the Foundation's common web interfaces, this just doesn't work. Correct. > (c) Add modeling.mdt.ocl to the database that controls all of the web UI > driven by the > Project Meta-data, so that the PHP script will recognize it (once I have > filled in the meta-data) Not until the Board approves the new development process. That was supposed to happen in March and then in June and now who knows? Anyway, until the Board does that, OCL is not a reportable entity. The reportable entity is MDT and thus MDT needs to publish the project plan. The current development process (and thus roadmap process) does not envision separate plans for components.
(In reply to comment #62) > If they have the XSD, and add it to the XML Catalog for Web Tools, then they > will get content assistance. You can also setup validation to happen before > you even process the XML file to make sure that it is at least valid according > to the XSD. I would like to have that validation when editing my project plan. I installed Eclipse 3.4 plus the XML Editor from the Ganymede site, but where do I register your XSD? Also, is the one from the attachment still valid? Comment #71 seemed to indicate that some updates might be required. Right now, when I use XML editor on the project plan I do get warnings for invalid XHTML when I choose right-click > source > validate... but I feel that adding the XSD should give me some more...
(In reply to comment #76) > (In reply to comment #62) > > If they have the XSD, and add it to the XML Catalog for Web Tools, then they > > will get content assistance. You can also setup validation to happen before > > you even process the XML file to make sure that it is at least valid according > > to the XSD. > > I would like to have that validation when editing my project plan. I installed > Eclipse 3.4 plus the XML Editor from the Ganymede site, but where do I register > your XSD? Also, is the one from the attachment still valid? Comment #71 seemed > to indicate that some updates might be required. > > Right now, when I use XML editor on the project plan I do get warnings for > invalid XHTML when I choose right-click > source > validate... but I feel that > adding the XSD should give me some more... > The one from the attachment is not valid any longer. I'll see if I can get it updated. I'll give some instructions after I update it to match the current layout.
Created attachment 109230 [details] Updated Project Plan Schema to work with New Format XSD that validates the most current XML project plan format. To use this add: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="projectplan.xsd" to the <plan> root element: <plan xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="projectplan.xsd"> Change the noNamespaceSchemaLocation to where you have the projectplan.xsd file stored. This will allow Content assistance using the XML Editor from Web Tools to be used.
Created attachment 109231 [details] Corrected issue with Target Environment element. Fixes validation issue with target environment, same process still works for adding content assistance.
I very much dislike no namespace schemas. Wouldn't it be better to have a namespace and then it's much more likely we could define a content type in Eclipse to recognize it and it would be possible to use the XML catalog to register the schema for the file (and thereby avoid putting this xsi data in the instance file)? It seems odd (redundant) to declare the elementFormDefault to be qualified for a no namespace schema. If we had a namespace, we'd perhaps not want to require that qualification other than on the root "plan" element. If we made the namespace be the actual location of a schema file on the web site, we could avoid even messing with the XML catalog... Would anyone object to assigning a namespace for this type of document?
(In reply to comment #80) > I very much dislike no namespace schemas. Wouldn't it be better to have a > namespace and then it's much more likely we could define a content type in > Eclipse to recognize it and it would be possible to use the XML catalog to > register the schema for the file (and thereby avoid putting this xsi data in > the instance file)? It seems odd (redundant) to declare the elementFormDefault > to be qualified for a no namespace schema. If we had a namespace, we'd perhaps > not want to require that qualification other than on the root "plan" element. > If we made the namespace be the actual location of a schema file on the web > site, we could avoid even messing with the XML catalog... > > Would anyone object to assigning a namespace for this type of document? > Ed when the xml file was originally being designed I had proposed using the namespace http://www.eclipse.org/project/plan for the elements, and also instead of HTML, that XHTML should be used to describe the content. I'd rather have namespaces as it makes it much easier to deal with the wildcard characters that the current design is enforcing. Anyways, I think this topic in itself on the project plan format should probably be in it's own bug.
Dave, I agree. Given that this bugzilla is closed, I think it makes sense to open a new bugzilla with your schema and propose that it have a namespace. I can't imagine any strong objections to having a namespace. Clearly doing so will make the possibility of tool support for this better in the future and even today; it's easy to generate an EMF model from this schema.
I've opened bug 243303 to track the namespace request and schema update from this bug.
(In reply to comment #15) > I like Martin's idea of just marking things as plan items. I've always > questioned this "theme" thing as something folks will pay lip service too > because someone else decided the themes for them and now their plans need to be > fit into a shoe they didn't help design. (In the past, someone has always told > me "These are the themes." I don't expect that to change and hence I don't > expect the themes to be all the useful for categorizing my plan.) > For bug-based plans, I actually think we need something just a little more fine-grained than a 'plan' keyword. In order to preserve the content of a plan from one release to another, particularly for items that get deferred in one release and committed/planned in another, I think we should have a keyword for each simultaneous release - I've opened bug 247191 to request this. The idea is the following: - committed bugs for galileo are all those that have a keyword of galileo and a target milestone of <v Mn> (3.5 M1, etc.). - planned bugs for galileo are all those that have a keyword of galileo and a target milestone of <v> (3.5, etc.). - deferred bugs for galileo are all those that have a keyword of galileo and a target milestone other than <v Mn> or <v>. During the next release (say we call it 'Foo'), we use a 'foo' keyword for items in the plan. If we now decide to commit to one of the deferred items from Galileo, we add the 'foo' keyword to it and set a target milestone. The old plan (for Galileo) still shows the item as deferred and the new one shows it as committed, as desired.
(In reply to comment #84) When I read you right, the issue can only happen for deferred plan items (was it deferred in galileo or foo?) - since "committed" and "proposed" items are uniquely identified by the target milestone in your proposal (3.5 != 3.6). I'm a little reluctant regarding different keywords for each release train, since (a) they won't work for projects releasing off the train and (b) they will get more and more. In fact, if you are very concerned about plans changing after the fact, you'll likely need to convert a frozen version of the plan into HTML at some point since it's just too easy to "lose" a plan keyword at some point. Another solution, assuming that you plan your items judiciously by adding a "plan" keyword and thus don't need to defer an item too often, would be to just make a Bugzilla Advanced query searching for a Comment reading "Deferred in Galileo" or whatever markup you'd want to have.
(In reply to comment #85) Thanks for the feedback. Let's conduct the remainder of this discussion on bug 247191.
