Community
Participate
Working Groups
+++ This bug was initially created as a clone of Bug #468491 +++ Our readme HTML file exists both "in the product", and on our web pages (there with a PHP script around the HTML copy). The version included in product, is in /org.eclipse.rcp (feature)/rootfiles/readme/readme_eclipse.html in the eclipse.platform.releng Git repo. The versions for the web are (or will be) in /development/readme_eclipse_4.6.html /development/readme_eclipse_4.6.php For reference, here is the URL for the previous (4.5) version https://www.eclipse.org/eclipse/development/readme_eclipse_4.5.php = = = = = = So far I have taken a very quick pass to do some blanket updates of "4.5" to "4.6", and similar, to serve as a starting point. The basic method we will use it to update the web version, and then with each RC update the version in the feature /org.eclipse.rcp (feature)/rootfiles/ You can make revisions directly, assuming you have access to our "website repository" at ssh://<committerId>@git.eclipse.org/gitroot/www.eclipse.org/eclipse.git (I am unsure if there is "gerrit access" but if not we should arrange for that). And, as far as I know, all project leads should have website access. Be sure to review carefully not only for accuracy, but also "things to add", and also for "things to remove" (that is, remove things that are no longer true, or have moved to help documentation, or similar.
New Gerrit change created: https://git.eclipse.org/r/72440
Gerrit change https://git.eclipse.org/r/72440 was merged to [master]. Commit: http://git.eclipse.org/c/www.eclipse.org/eclipse.git/commit/?id=071683144c0357577f35b54aabfe2a3b0072bb22
(In reply to Eclipse Genie from comment #2) > Gerrit change https://git.eclipse.org/r/72440 was merged to [master]. > Commit: > http://git.eclipse.org/c/www.eclipse.org/eclipse.git/commit/ > ?id=071683144c0357577f35b54aabfe2a3b0072bb22 Yep. Gerrit works! I should have given clickable links to current (4.6) readme: https://www.eclipse.org/eclipse/development/readme_eclipse_4.6.php https://www.eclipse.org/eclipse/development/readme_eclipse_4.6.html = = = = = I also meant to say, after saying "You can make revisions directly, ..." that you can also attach patches here, or -- if crystal clear -- document what you would like added or removed and I can try to edit, subject to your review. (Usually easier to "do yourself" ... but, just offering to help if easy). While we can update the web readme at any time (even after the release) the one that goes in the product must be complete. Let's target to have that version complete by RC3, so that we will not have to respin RC4 merely for the readme file. According to our build schedule, https://www.eclipse.org/eclipse/platform-releng/buildSchedule.html the RC3 build takes place on May 25. Working backwards, that means May 18 (RC2) should be your deadline for getting your input and edits done, to give one week for review, questions, and refinement before the final version is "built". That is next week! Try to complete at least a first pass by RC2 (May 18) and then have final input by May 25. Please comment here in bug when "your" component is "done" so I know who to track down and pester. :)
I have pasted and committed what we have so far into the org.eclpse.rcp feature rootfiles folder. We do not have much, so far, -- just the changes I made -- but figured it would be good to sanity check that it is indeed that file that gets included with all the "products". (99% sure, but doesn't hurt to be 100% :) Appears some formatting changes were introduced too. http://git.eclipse.org/c/platform/eclipse.platform.releng.git/commit/?id=366bcad0c747e039a6bc849f661908a4cc5cdf2b
There is a paragraph on "permgen size" = = = = = When using an Oracle VM below 1.8, you may also need to increase the size of the permanent generation memory. The default maximum is 64 megabytes, but more may be needed depending on your plug-in configuration and use. When the VM runs out of permanent generation memory, it may crash or hang during class loading. This failure is less common when using Oracle JRE version 1.5.0_07 or greater. The maximum permanent generation size is increased using the -XX:MaxPermSize=<memory size> argument: eclipse -vmargs -XX:MaxPermSize=<memory size> This argument may not be available for all VM versions and platforms; consult your VM documentation for more details. = = = = = I am going to delete that entire paragraph since no longer relevant.
(In reply to David Williams from comment #5) > There is a paragraph on "permgen size" > = = = = = > When using an Oracle VM below 1.8, you may also need to increase the size > of the permanent generation memory. The default maximum is 64 megabytes, but > more may be needed depending on your plug-in configuration and use. When the > VM runs out of permanent generation memory, it may crash or hang during > class loading. This failure is less common when using Oracle JRE version > 1.5.0_07 or greater. The maximum permanent generation size is increased > using the -XX:MaxPermSize=<memory size> argument: > > eclipse -vmargs -XX:MaxPermSize=<memory size> > > This argument may not be available for all VM versions and platforms; > consult your VM documentation for more details. > = = = = = > > > I am going to delete that entire paragraph since no longer relevant. Here's the commit that removed the paragraph. http://git.eclipse.org/c/www.eclipse.org/eclipse.git/commit/?id=9767723ddbe0df37d4886b7d72a689eebe243296 Note: the following sentence (continues) talking about "max heap" and says "setting memory sizes to be larger than the amount of available physical ..." I changed to say "setting memory sizes to be near or larger than the amount of available physical ..." since the reality is, a lot of memory if consumed by other parts of the system and other software, so the reality is you can be much higher than "half" of available physical memory. Personally, I think since this is "general VM information" I am not sure we should include it at all -- but, admit, it is a common problem with Eclipse so I guess not much harm in giving a hint.
There were several other mentions of "PermGen size" which I removed with the following commit. http://git.eclipse.org/c/www.eclipse.org/eclipse.git/commit/?id=a7efb3bdbb942dcc0ed2e017f96c5b0819266b2c (As of recent builds, "maxpermgen" should no longer be part of our "eclipse.ini".)
With this commit, I "half blindly" removed mention of "Java 7". http://git.eclipse.org/c/www.eclipse.org/eclipse.git/commit/?id=f6ddeb82e9e8268f74b0126c948edd0de3ce8963 By "half blindly" I mean there might be formatting issues or something due to the removal, which I did not check. In fact, in the past, we changed the "plugin BREE requirements just to point to the 4.6 plan -- I am thinking we should do the same thing for the target environments so that we do not have duplicate information in two places.
With this commit, I moved the previous clickthroughs to the readme file. See also bug 493856 for background of the move. http://git.eclipse.org/c/www.eclipse.org/eclipse.git/commit/?id=a087d54ec4b03c2cf7661255f5120be805e310a2 We may have more work to do on formatting. I noticed these don't show up in the TOC. I guess the TOC is manually produced?
Following up on my comment 8, I did move the "target environments" to be a link pointing to the Eclipse 4.6 plan. http://git.eclipse.org/c/www.eclipse.org/eclipse.git/commit/?id=c9a79dc9ea564c49d8a64706f61ef2b4ef2524c1
I did, btw, correct a few other minor HTML syntax errors, and also replaced the version in the rcp feature with the new contents, so the version in tonight's (5/22) I-build should be "the latest" (unless others make changes).
Reviewed Read me changes for Platform Ant, Debug and JDT Debug. Removed one entry for Platform Ant which does not seem to be relevant now. http://git.eclipse.org/c/www.eclipse.org/eclipse.git/commit/?id=0cdc53383df7a23689b7306650cadd97e75c8bcd
Reviewed for JDT/UI. No change required.
Found one item (bug 188558) where we have no plan to fix. I wonder if we should remove that. I have raised that in the bug (which has no update for past 8 years) and depending on the response, might just remove it from the readme.
Reviewed for Platform Resources. No change required.
I don't know why we have not done this before (if there is a good reason, let me know and I'll remove) but I have added an initial paragraph to the readme that says (to paraphrase) "For the latest version of this document see the web version" That's just to give a hint in case we do make changes after the product is built and released. This paragraph should be "commented out" in the web version, but have left is "in" for now. It also makes it more important to remember to update "last modified" date at the top of the document, if changes are made after the release. http://git.eclipse.org/c/www.eclipse.org/eclipse.git/commit/?id=1a3a64509eab387db5059c1321126dec22388230
I have applied HTML formatting to the readme_eclipse_4.6.html file to make it easier to read as HTML. I think JDT should review the section with an h3 heading called "I-General-64bitJava". It mentions "Java 6" and I am not sure the problem still exists? It refers to bug 214092 which was closed as "not eclipse" (i.e. VM problem). The "Ant Team" should review the section titled "Ant Editor code completion based on Ant 1.6.x" -- Ant 1.6.x is very very old! And SWT, don't forget to review the new section "Special Operating System Requirements". These were the old clickthroughs which I just copied verbatim. If nothing else, some versions may need to be updated? Such as for AIX? (I'm just guessing -- I've not compared to "supported platforms").
(In reply to David Williams from comment #17) > I think JDT should review the section with an h3 heading called > "I-General-64bitJava". It mentions "Java 6" and I am not sure the problem > still exists? > It refers to bug 214092 which was closed as "not eclipse" (i.e. VM problem). Is it even relevant now that we no longer support older versions of JVM for Eclipse IDE?
(In reply to Jay Arthanareeswaran from comment #18) > (In reply to David Williams from comment #17) > > I think JDT should review the section with an h3 heading called > > "I-General-64bitJava". It mentions "Java 6" and I am not sure the problem > > still exists? > > It refers to bug 214092 which was closed as "not eclipse" (i.e. VM problem). > > Is it even relevant now that we no longer support older versions of JVM for > Eclipse IDE? IMO it is not. But I know some entries were written when Java 6 "was the latest", so it depends on if relevant to "the latest" VMs (and if so, the section and workaround tailored "the latest" VM). But if very specific to Java 6, I'd dump it. I also know we require Java 8 to "run", but not sure what versions of Java we support development for. For example, some few people may need to apply maintenance to code that still runs on Java 7 or even Java 6, But IMHO, those (especially Java 6) would be so rare, I think we just clutter up the readme mentioning "every possible bug" someone might encounter.
(In reply to David Williams from comment #19) > I think we just clutter up the readme mentioning "every possible bug" someone > might encounter. I agree.
(In reply to David Williams from comment #19) > IMO it is not. Then can we get rid of this, please? I have trouble pushing changes to this project. I would appreciate if someone can do it for me. Manoj, can you please? Thanks!
Tonight I made several changes of significance. 1. I deleted the whole section mentioned in comment 17 about a bug in Java 6. 2. I removed sections that said "none" (If there's nothing to say, say nothing :) But, more so, most users do not care about our "components". If anything the "component sections" should refer to functionality. 3. I removed some "platform notes" that were clearly 4 or 5 releases old (such as you can not just put a new plugin into plugins folder). I am sure it was done "at the time" because it was "new behavior" -- but, users need to have that level of operation explained, it belongs somewhere besides the release notes. 4. I added a "computed" Tabled of Contents, completely at the beginning. First, because I think that is much easier for users to scan through, to see if there is anything relevant to them. Second, I hope it makes it easier for you project leads to see the extent of all the old crap that is in there, and how long and pointless it is. I don't mean to sound *that* critical (it is "mine" too! :) but it us unlike any other readme's or release notes I have ever seen. I am not sure there is time to do it this release, but in the future, I think best to have release notes that apply only to that release, with a pointer to where ALL the release notes are, and mention that "if jumping from an old release to this current release, be sure to scan through the other release notes between the two". (only worded better). So ... project leads ... further improvement before tomorrow's RC3 build is up to you to perform! (or, add a patch or be explicit what you would like done). Technically, we can add or improve at any time, but it would just be for the "web version". Thanks all.
(In reply to David Williams from comment #17) > The "Ant Team" should review the section titled "Ant Editor code completion > based on Ant 1.6.x" -- Ant 1.6.x is very very old! > I think it still makes sense and should not be removed.
Is everyone done? I am. This morning I edited the document to be compliant with "XHTML1 strict", as per <http://validator.w3.org/check?uri=http%3A%2F%2Fwww.eclipse.org%2Feclipse%2Fdevelopment%2Freadme_eclipse_4.6.html;ss=1> and regenerated the "table of contents", update copyright date, and updated "last modified date" and added latest copy to RCP feature root files. If anyone has more to do, please feel free to re-open. (I could appreciate authors checking valididy at above URL once done editing. Thank everyone for your updates and checking.
Oh, I also wanted to document here I created the Table of Contents using some free editor named KomopZer (on Linux). It is not "state of the art" but the only quick and easy solution I could find. I just now noticed it's "table of contents" does not display on the "solstice version" at https://www.eclipse.org/eclipse/development/readme_eclipse_4.6.php So, if anyone knows of some better tools or XSL (or JavaScript1?) to easily generate a TOC, that's fine. I am just running out of time to do more. I mention the tool I used in case anyone wants to use it to "remove" the TOC, I think it will remove most of it (but, may leave it bits of stuff that have to be hand removed, from my experience). Thanks,
Reopening as I've added a couple of new entries for SWT to the readme via http://git.eclipse.org/c/www.eclipse.org/eclipse.git/commit/?id=b86e16fdf3b52d8edb7c98ab0e8b49502a6335e2
(In reply to David Williams from comment #24) > Is everyone done? > > I am. This morning I edited the document to be compliant with "XHTML1 > strict", as per > > <http://validator.w3.org/check?uri=http%3A%2F%2Fwww.eclipse. > org%2Feclipse%2Fdevelopment%2Freadme_eclipse_4.6.html;ss=1> > > and regenerated the "table of contents", update copyright date, and updated > "last modified date" and added latest copy to RCP feature root files. > > If anyone has more to do, please feel free to re-open. (I could appreciate > authors checking valididy at above URL once done editing. > > Thank everyone for your updates and checking. I forgot to mention that I did validate the file after making changes and before pushing to git... thanks!
I have updated the "TOC" and put the new version into the rcp feature's rootfiles. Please proofread carefully since that tool to create the TOC is terrible at "updating". It left a lot of "empty link elements" in inappropriate areas, thus spoiling the XHTML validity. I tried to be careful editing those out, but, there were 70 or 80 so a "typo" would not be out of the question. We must find a way (and invest the time) to create a proper TOC ... someday.
Viewing https://www.eclipse.org/eclipse/development/readme_eclipse_4.6.php in Firefox major parts of the document are rendered as links (though not pointing anywhere). Looks like anchors like this <a class="mozTocH2" name="mozTocId569479" /> are interpreted as *opening* tag lacking a closing tag. In Firefox "Show Source" shows this as <a class="mozTocH2" name="mozTocId569479">Compatibility with Previous Releases</a> The only thing that truly terminates such runaway anchor-elements is the next anchor in the source. This does not apply to the bare .html page. The php version doesn't expect / understand xhtml?
(In reply to Stephan Herrmann from comment #29) > Viewing https://www.eclipse.org/eclipse/development/readme_eclipse_4.6.php > in Firefox major parts of the document are rendered as links (though not > pointing anywhere). > Looks like anchors like this > <a class="mozTocH2" name="mozTocId569479" /> > are interpreted as *opening* tag lacking a closing tag. > > In Firefox "Show Source" shows this as > <a class="mozTocH2" name="mozTocId569479">Compatibility with Previous > Releases</a> > > The only thing that truly terminates such runaway anchor-elements is the > next anchor in the source. > > This does not apply to the bare .html page. > The php version doesn't expect / understand xhtml? Beats me. I think it is more of an "HTML5" issue? But fundamentally, those funny anchor tags are the results of trying to "insert" a Table of contents with an old tool and is not really the right way to do it. Someday, myself, or someone else, will do our table of contents using a modern method. I ran out of time for Neon release, but we can change the web version at any time, and put it in sync with the in-distribution one in Neon.1.
(In reply to Stephan Herrmann from comment #29) > Viewing https://www.eclipse.org/eclipse/development/readme_eclipse_4.6.php > in Firefox major parts of the document are rendered as links (though not > pointing anywhere). Same in other browsers as well. > but we can change the web version at any time, and put it in sync with the > in-distribution one in Neon.1. Reopening this bug which is explicitly about the web version.
(In reply to Stephan Herrmann from comment #29) > Looks like anchors like this > <a class="mozTocH2" name="mozTocId569479" /> > are interpreted as *opening* tag lacking a closing tag. I don't see such short tags anywhere in readme_eclipse_4.6.[html|php]. These non-link anchors really do contain the embedded text. In the readme_eclipse.html shipped with the install, this is not an issue, since the page uses default browser styles, which use internal tweaks to render only <a href=".."> tags as links, but leave <a name=".."> tags untouched. The problem in readme_eclipse_4.6.php is that the styles.min.css from solstice/bootstrap declares something like this: a:hover { text-decoration: underline; } This makes all links including all non-link anchors look like links when hovered. The best solution would be to use "id" attributes instead of <a name=".."> tags to declare internal targets. But to avoid introducing tons of differences in the two readme files at this point, we can also add some CSS that reverts the styles.min.css changes for <a name=".."> tags. Done with http://git.eclipse.org/c/www.eclipse.org/eclipse.git/commit/?id=933b20568000eef7e87bf863bf9058fe2bbe0d89 (and a parent commit that didn't work because _projectCommon.php doesn't process all of <head>'s children).
(In reply to Markus Keller from comment #32) Bug 495690 has fixed this globally in Solstice. Reverted workaround with http://git.eclipse.org/c/www.eclipse.org/eclipse.git/commit/?id=014811b5aac9265d3cc5db0cc9418cff2d57e8c9
