Community
Participate
Working Groups
In order to accomplish two goals of the 3.2 release, the Eclipse Project documentation plugins need to be moved from the "code" features that currently include them to separate documentation features. The two goals are: 1) Enable the update (via update manager) of documentation after the release independently from the "code" features. 2) Enable the support (provision of documentation fixes via updates) of translation of the documentation after the 3.2 release date without having to wait until the first maintenance release. There needs to be at least one documentation feature for each subproject that included documentation (Platform, JDT, PDE). Ideally, there would be separate features for end user and ISV documentation since some downstream products only want the end user documentation and it is common industry practice to only translate end user documentation and not ISV documentation. In addition, the ISV documentation features should only be contained in the SDK packages on the download site and not the runtime packages. It was recommend that this enhancement request start in the Releng component since this is where feature / packaging changes are often implemented.
I have a few questions regarding your requirements: 1)Would it be sufficient to create doc features that are only used for update site purposes? These features would not be included in the actual zips with the release. The doc plugins would remain in the zips provided with the build, no new doc features would be added. We cannot provide updates to ISV doc separate from the "code" because it contains javadoc and requires a full source tree to generate. Or in other words, the new ISV doc plugin would not reflect the code in the the rest of the eclipse install. 2) My understanding is that the time interval between the platform API freeze and the actual release date is sufficient for translations for the platform. NL translation packs are currently provided separately from the release. It's not a requirement to wait for a maintenance release to release the translations. However, translations are usually delivered after a maintenance release to incorporate all the bug fixes.
Created attachment 33827 [details] Projects for the proposed features Kim, this attachment contains 5 projects. One each for the proposed documentation features (not 6 since PDE does not have any ISV docs).
With regard to comment 1, I think we should include these features in the release so that users will know that there may be separate doc updates. This will provide a good mechanism for improving the docs out of band of the releases. Also, I think we need them for the ISV docs because not all the content in the ISV docs is generated. Some of it is hand crafted. These new features can be incorporated into the existing download zip packages. There is no need to invent new downloads nor would we have to remove the doc plugins from the features that currently contain them. It is my understanding that overlapping features are supported by the update manager. As for the timing, the desire was to have the translations done at Platform/Callisto GM time. Given the last minute nature of doc updates, this was deemed not to be possible. The English will be done at that time and we do not want to hold up doc translation availability until the first fix pack, however, we do need a way to service the English documentation in support of the translation effort. That is why Kevin and I agree on this doc feature route. Note that most of the other Callisto projects had doc features in their previous releases and it has worked fine for them.
I discussed this issue with Mcq, Jeff and Sonia There are issues with versions and overlapping features. Sonia another approach. She suggested we move the existing doc plugins out of the existing features into a new doc feature for every plugin. Then we could nest these new doc features in the in the existing platform, pde and jdt features. However, this causes issues with versions. For instance, if we only upgraded the version of the platform.doc.isv feature, the org.eclipse.platform feature would still refer to the old version of the platform.doc.isv feature. Consequently, there would be red Xs in Help->Software Updates->Manage Configuration. So Sonia suggested the only way to overcome this would be to create a new top level doc feature that is on the same level as the sdk feature. This feature could be packaged with the Eclipse SDK on the downloads page. Otherwise, Help would not have any content. This separation would provide the future ability, if required, to decouple the doc content from the sdk download. So, we need a PMC decision if we should proceed with creating a top level doc feature, yes or no? If yes, I will proceed with the testing and implemention but it must before M5.
I've been arguing that we should separate the doc from the sdk download for years, but Jeff reminded me that an "SDK" actually needs the doc. A better separation would be a "Java IDE" download with all the other pieces (i.e. doc + PDE) as an add on. Adding Jeff to the CC to get his comments on how to proceed.
result of conf call If required we will a build against the release build maps + updated doc plugin versions and rev the associated but existing features for release on an update site.
*** Bug 287475 has been marked as a duplicate of this bug. ***
*** Bug 287474 has been marked as a duplicate of this bug. ***
*** Bug 287473 has been marked as a duplicate of this bug. ***
Jim, in one of our next Eclipse PMC calls we will reconsider the WONTFIX decision and let you know here.
Thanks, Dani. Just to make sure it's captured here, there is a third goal to Jim's bug that wasn't captured in this original request: 3) To allow Eclipse adopter products to decide whether or not to ship documentation with the product. (this will also allow adopter products to make docs an install option, or provide it on the web, etc.) The reason for this is that documentation is usually a relatively large part of the download & install. Just as an example, there is about 94Mb of docs in WTP & prereqs (about 36% of the ~260Mb plugins on disk).
We can't simply remove the doc from the features that currently include them, since that would break existing clients who expect our feature contents to be stable. For example if a client upgrades org.eclipse.platform from 3.5 to 3.6 and this causes documentation to be deleted, they will be broken. We could support this by splitting org.eclipse.platform into two new features that would be included by org.eclipse.platform: org.eclipse.platform.doc and org.eclipse.platform.binary for example. That would allow a consumer to choose to consume only the binaries, or the binaries+doc. In general this approach of splitting features for each subset people want to consume is not scalable. In the extreme we end up with one feature per plug-in, and the feature concept loses all value as a grouping mechanism. There is another approach to this problem supported by p2. p2 allows filters to be added to a dependency, and that dependency will be traversed at install-time only if that filter is satisfied. For example documentation could have a filter such as (org.eclipse.exclude.doc=false), which would be satisfied by default for compatibility purposes, but would become unsatisfied if someone added the property "org.eclipse.exclude.doc=true" to their application's profile. Filters give more flexibility to slice and dice the platform in different ways without an explosion of features (say one client wants doc but not source, another wants doc+source, and another wants source but not doc, etc).
(In reply to comment #12) > ... > In general this approach of splitting features > for each subset people want to consume is not scalable. > Seems to me "docs" is a fundamental division and this fear of not scaling is a bit extreme in this case. Seems to me there should be some general model or architecture of what the right division or grouping of installable units should be ... and that to say "clients can do the slicing and dicing however they'd like" is a bit of a cop-out. It seems to me there are three obvious divisions (that we've argued about for years :) 'code', 'end-user docs', 'extender docs', and 'source'.
(In reply to comment #13) > (In reply to comment #12) > > It seems to me there are three obvious divisions (that we've argued about for > years :) > > 'code', 'end-user docs', 'extender docs', and 'source'. Er, that's four ... I split docs into two types as I typed, thus strengthening your argument (ha ha). But, let's say someone wanted to advocate the P2 approach you mention ... that means the provider still has to "label" each bundle with appropriate properties, right? So we'd still need some model of what to label them with, right? Can you imagine a recommendation as a Planning Council for all projects to follow? Seems it'd be a possible solution for "source vs. no-source" installs. Also, be sure to cover the case where documentation-only is desired ... no code ... such as if someone wanted to "install" into an InfoCenter? How would they specify the installable and the property constraint then? (I have a feeling there's an obvious answer ... just not obvious to me). Much thanks.
>But, let's say someone wanted to advocate the P2 approach you mention ... that >means the provider still has to "label" each bundle with appropriate >properties, right? So we'd still need some model of what to label them with, >right? Yes, this would work just like the filters we have in feature.xml today such as os="win32". There would need to be consistent labelling of these attributes and their values. So it's more work for the provider to define these labels but less work for the consumer (who otherwise needs to dig through the features and figure out what is source, binary, doc, etc). >Also, be sure to cover the case where documentation-only is desired ... no code >... such as if someone wanted to "install" into an InfoCenter? How would they >specify the installable and the property constraint then? (I have a feeling >there's an obvious answer ... just not obvious to me). I don't know how InfoCenters are installed today, but I suspect they don't use our features at all. However in theory if every bundle had an attribute on it (such as "doc", "binary", or "source"), you would be able to express that with filters too. (doc="true", binary="false", source="false" in this case).
Jim and Tim, as John already said we cannot restructure the stuff at this point (at least not in the 3.x stream). Would John's approach work for you?
Reopening because we are actively discussing the issue.
I have opened bug #288310 in order to discuss feature reorganization in the context of e4.
John's approach sounds like the correct solution, but since this is a new p2 feature I want to ensure our installer can make use of it first. Sent mail to our install team and cc'd Pascal to confirm.
Although p2 already supports such filters, there would be some work required here to add authoring-time support. I'll start this discussion in PDE to see if this support can be added. The other limitation with install filters that Pascal pointed out is that they are global in scope. Thus this would result in an "all or nothing" solution where all documentation is installed or none. This might be the right answer in some cases but is somewhat limited.
And another thing to consider is the behavior of the old update manager in the presence of such filters. It may break ppl using those features in a pure update manager world.
I've confirmed that our installer doesn't currently support this type of filtering, but like PDE could be made to in time for the 3.6 release. I understand there are issues still to work out, but would like to proceed with this change.
I like the idea of using 'code', 'end-user docs', 'extender docs', and 'source' as four "Eclipse standard" properties since it seems like any functional feature (such as "Java Editor", "XML Editor") could indeed have these 4 parts (in principle .. some might not literally). One thing I wanted to mention though, in case impacts this issue, is how does this intersect with feature patches? For example, could a patch still be made for exactly one plugin? (even if, for example, the original installed version had both "code" and "source" bundles ... would the patch have to include both types?
*** Bug 278851 has been marked as a duplicate of this bug. ***
Just to restate. There are 4 different properties optionally added to a bundle's manifest: 'code', 'end-user docs', 'extender docs', and 'source' The p2 metadata generator will generate a <unit> <filter> expression for the bundle based on the property in the manifest. Will the ability to set the property in the profile be exposed through the p2 update ui?
(In reply to comment #25) > Just to restate. There are 4 different properties optionally added to a > bundle's manifest: > 'code', 'end-user docs', 'extender docs', and 'source' No, I was thinking of a filter on the feature that includes a given bundle. The dependency from the feature to the bundle would depend on the satisfaction of the filter property (as we do today with os/ws/arch filters). This is a bit more flexible because it delegates the decision about what is "user doc", etc, to the feature. It would also allow someone to explicitly install a particular piece of user doc even if the "install user doc" property wasn't set on the profile.
comment 26 makes more sense then comment 25 In order to install the doc without "install user doc" property set in the profile, would the individual doc <unit>s for the bundles need to be <required> ?
(In reply to comment #27) > In order to install the doc without "install user doc" property set in the > profile, would the individual doc <unit>s for the bundles need to be <required> Yes. Essentially by default the features would require the doc bundle with a conditional requirement based on the presence of a profile property. Another feature could come along and make an simple (unconditional) dependency on a doc bundle, which would cause that doc bundle to be installed regardless of any properties set on the profile.
I raised bug 293715 to support specifying filters in the feature.xml Features containing doc bundles can define arbitrary filters something like: (| (!(install.docs=*))(install.docs=any)(install.docs=isv)) The above filter passes when the profile doesn't contain the install.docs property or has install.docs=any or install.docs=isv
This bug hasn't had any activity in quite some time. Maybe the problem got resolved, was a duplicate of something else, or became less pressing for some reason - or maybe it's still relevant but just hasn't been looked at yet. If you have further information on the current state of the bug, please add it. The information can be, for example, that the problem still occurs, that you still want the feature, that more information is needed, or that the bug is (for whatever reason) no longer relevant.
