Bugzilla – Full Text Bug Listing
| Summary: | 4.4 API change report is not accurate. | ||
|---|---|---|---|
| Product: | z_Archived | Reporter: | Paul Slauenwhite <paulslau> |
| Component: | TPTP | Assignee: | Kendric Wang <kendricw> |
| Status: | CLOSED FIXED | QA Contact: | |
| Severity: | major | ||
| Priority: | P1 | CC: | andrewp, chris.l.elford, jcayne, jgwest, jkubasta, jptoomey, kendricw, popescu, sluiman, smith, stoian, xubing |
| Version: | unspecified | Keywords: | plan |
| Target Milestone: | --- | ||
| Hardware: | All | ||
| OS: | All | ||
| Whiteboard: | |||
|
Description
Paul Slauenwhite
Please be more specific on what is inaccurate. Do you think the build is running the report on a wrong version of TPTP, or the tool simply produce incorrect output. The report tells you exactly what are changed. Please provide an example where the claim is incorrect. Paul, could you please comment? I need to know if this needs to be fixed in 4.4. Thanks. (In reply to comment #1) Hi Hubert, apologies for not providing more detailed information. Based on the http://download.eclipse.org/tptp/4.4.0/jdiff/Testing_Tools/public/changes.html, there are numerous instances where API are tagged as changed, but the source files have not been modified in the 4.3 or 4.4 time frame. For example, the org.eclipse.hyades.test.ui.navigator.DefaultTypedElementProxyFactory class: http://download.eclipse.org/tptp/4.4.0/jdiff/Testing_Tools/public/changes/org.eclipse.hyades.test.ui.navigator.DefaultTypedElementProxyFactory.html#org.eclipse.hyades.test.ui.navigator.DefaultTypedElementProxyFactory.create_removed(org.eclipse.hyades.models.common.testprofile.TPFExecutionResult,%20java.lang.Object) According to CVS, this file has not been changed in HEAD for the last 14 months: http://dev.eclipse.org/viewcvs/index.cgi/test/org.eclipse.hyades.test.ui/src/org/eclipse/hyades/test/ui/navigator/DefaultTypedElementProxyFactory.java?root=TPTP_Project&view=log In my opinion, if this cannot be fixed in 4.4, we should remove these reports since they give the impression that the latest TPTP releases are volatile, from an API perspective. The API change report uses the javadoc as an input. The 4.4 javadoc: http://download.torolab.ibm.com/tptp/4.4.0/javadoc/Testing_Tools/public/index.html DefaultTypedElementProxyFactory javadoc: http://download.torolab.ibm.com/tptp/4.4.0/javadoc/Testing_Tools/public/org/eclipse/hyades/test/ui/navigator/DefaultTypedElementProxyFactory.html For some reason, some methods don't show up in this javadoc. So this problem is related to javadoc and not jdiff. (In reply to comment #3) Hubert, these are internal links that appear to be broken. I can only access the JavaDocs at http://www.eclipse.org/tptp/home/documents/resources/javadoc.html. Are the JavaDocs generated for every build? Since I cannot confirm the contents of the 4.4 JavaDoc, can you send me the commands used to generate these JavaDocs so I can determine why some methods are missing? Can we get this addressed today please? If not, we need to remove these reports from the web page. Severity increased to BLOCKER at PMC request This one has been fixed. Paul can you review the result. Here is our solution: When a method that is overloaded multiple times and the classpath argument of Javadoc does not point to the argument's package, the compiler treats it as a generic object. To fix this we provide a command line argument file containing the complete classpath including the top level packages. This is to avoid the error of the classpath being too long. The reports look much better but they still contain experimental provisional API (e.g. *.provisional.* packages). Since experimental provisional API is API that has a high risk of change in the next release, I would assume it should not be included in this report. Even stable provisional API should probably be removed from this report. Joanna, can you request a clarification from the PMC? De3creasing severity since the initial blocking issue has since been resolved. (In reply to comment #8) Source: http://www.eclipse.org/tptp/home/documents/process/development/api_contract.html the term experimental is not one we use. Many of the last several release reviews state the different levels of provisional API. Two styles of Provisional being applied to new functional areas: -API is stable and will maintain binary compatibility forward Platform javadoc Provisional - javadoc with provisional tag, Provide contract description and samples, Risk is implementation reliability -API is deemed final, but is not 100% guaranteed, however is available for usage Platform package Provisional - Not part of standard package - requires an explicit download, Provisional package name, Contract and samples provided Has there been a regression? I am seeing the problem again that was reported fixed in Comment #7. Hi Dave, To my knowledge, the original defect has been fixed and the change in the javadoc that you noticed last week wasn't due to a regression. We were tweaking the run-javadoc.sh script last week, so I have a feeling that whatever "misleading" data you saw was actually generated by a test version of script. This is not the version checked into CVS/run during the builds, however, executing the script individually does copy generated files over to the official eclipse website, overwriting the already existing javadocs. For future testing, I will comment out those commands. A new build is available as of June 11th, 1 AM. Can you check over the javadoc to make sure it reflects clean information? Thanks and sorry for the inconvenience. The report is clean again. Thanks for the explanation. The javadoc has been updated to excluded provisional packages from the reports generated. Sun has a proposal for adding a tag to exclude specific classes, methods, and interfaces from javadoc generation(@exclude). However, this tag has not been implemented yet (http://java.sun.com/j2se/javadoc/proposed-tags.html). Joseph, we have checked in the changes to remove only provisional packages from javadoc reports. Do you think there is anything else to exclude or should we wait for Paul to return? updated target to 4.4.1 (In reply to comment #15) A couple of more issues: 1) The change report (http://download.eclipse.org/tptp/4.4.0/jdiff/Testing_Tools/public/changes.html) still contains provisional API (package *.provisional.*;) that have been removed. This can be confusing when provisional API (package *.provisional.*;) is promoted to stable API, appearing to be removed. This report should not contain provisional API (package *.provisional.*;), either changed/added/removed. 2) Some methods have provisional tags do not appear in the change report. For example, the methods in the org.eclipse.hyades.test.core.launch.delegates.BasicTestLaunchConfigurationDelegate2 class. However, other methods that contain provisional tags do appear in the change report. 3) Of less importance, some comments contain other JavaDoc tags (e.g. @author). This is inconsistent and they should probably be removed. For example, the interfaces in the org.eclipse.hyades.test.core.launch.extensions package. As per my discussions with Paul, here's a summary of the issues with the javadoc report and their related fixes: 1. "*provisional* packages, excluded from javadoc reports since 4.4.0, are shown in the jdiff (change report) between 4.4.0 and 4.3.0 as being removed" - only link to the jdiff is from the build report page; build report pages are only available for the current build - jdiffs for builds after 4.4.0 are accurate - have no mention of provisional packages being added/removed/changed - no fix needed since problem not applicable to builds after 4.4.0 2. "some methods with provisional tags do not appear with provisional comments in the change report" - cannot find an example of above problem; no fix required 3. "some comments contain other JavaDoc tags" (ie. @author) - disabled the @author, @version, and @since tags from appearing in javadoc reports 4. "private and protected APIs should not appear in the public JavaDoc or JDiff report" - javadoc options have been set such that only public APIs appear in future reports generated - until the release of 4.4.1 GA build, the current jdiff (between 4.4.1 and 4.4.0) will show private APIs as having been removed 5. broken links in the current (4.4.1) JDiff reports - the Javadoc reports for previous (4.4.0) build were archived - issue fixed by moving all the current and storing all the future JDiff and Javadoc reports in archives on the downloads page If these resolutions meet your satisfaction, please resolve this defect as "FIXED". Thanks =) Changes have been checked in. Changing to fixed. Looking really good guys! Still seeing some JavaDoc tags (@author and @generated): http://archive.eclipse.org/tptp/4.4.1/jdiff/Testing_Tools/public/changes/pkg_org.eclipse.hyades.test.tools.core.services.html#ImportExistingProjects http://archive.eclipse.org/tptp/4.4.1/jdiff/Testing_Tools/public/changes/pkg_org.eclipse.tptp.test.report.birt.services.html (In reply to comment #18) > 4. "private and protected APIs should not appear in the public JavaDoc or JDiff > report" > - javadoc options have been set such that only public APIs appear in future > reports generated > - until the release of 4.4.1 GA build, the current jdiff (between 4.4.1 and > 4.4.0) will show private APIs as having been removed Hi Joel, after reviewing 4.5 API report, it still contains protected API that have since been removed. For example: http://archive.eclipse.org/tptp/4.5.0/jdiff/Testing_Tools/public/changes/pkg_org.eclipse.hyades.test.java.runner.html#HyadesJUnitRunner.AgentConsoleStream In this case, AgentConsoleStream was a protected class that was removed (Aug. 22/07), but it still shows in the API report. I regenerated the API report for 4.4.0 so that protected and private classes should not show up in change reports for 4.5.0 and future releases. Verified that AgentConsoleStream does not appear in the latest (May 5/08) report. I tried to exclude the @generated and @author tags by using the -excludetag parameter available to the jdiff doclet (as specified in the jdiff documentation: http://javadiff.cvs.sourceforge.net/*checkout*/javadiff/jdiff/doc/jdiff.html), but this didn't remove anything. This can be looked at again if there's another solution available. Otherwise, if there are no other problems, I will resolve this defect as fixed. Resolving as fixed. Cannot verify in 4.4 since the 4.4 API change reports are no longer posted. However, verified in the 4.5.0 API change reports. Closing. |