| <?xml version="1.0" encoding="UTF-8"?> |
| <faq xmlns="http://www.eclipse.org/webtools/faq" |
| xmlns:faq="http://www.eclipse.org/webtools/faq" |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xsi:schemaLocation="http://www.eclipse.org/webtools/faq schemas/faq.xsd" |
| name="wtp committer faq"> |
| <category name="General"/> |
| <category name="Build/CVS"/> |
| <category name="Source Code"/> |
| <category name="Website"/> |
| <entry id="cvs_1" category="Build/CVS"> |
| <question>What is the CVS info for the webtools project?</question> |
| <answer> |
| server : dev.eclipse.org<br/> |
| path : /cvsroot/webtools |
| </answer> |
| </entry> |
| <entry id="website_1" category="Website"> |
| <question>Who maintains the WTP website?</question> |
| <answer> |
| The WTP website is maintained by the WTP committers.<br/> |
| <br/> |
| Problems and requests should be submitted by opening a <a href="https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Web%20Tools&component=website">bug report</a>. |
| </answer> |
| </entry> |
| <entry id="website_2" category="Website"> |
| <question>How do I update the WTP website?</question> |
| <answer> |
| <p> |
| There are two ways: |
| <ol> |
| <li> |
| Check-out the whole website (www/webtools), make your changes, and run |
| the website build script (build.xml) in the webtools folder. This will |
| build the whole site and is useful if you need to make changes in more than |
| one module (see below). The downside is the website is big and can take |
| a while to download. |
| </li> |
| <li> |
| The website is broken up into self contained modules such as community, faq, people, |
| and plans. Check-out the module you want to make changes to (such as www/webtools/plans), make your changes, |
| run the build script (build.xml) included in the module, and commit your changes. |
| </li> |
| <li> |
| More recently, the switch to a Phoenix-enabled site has made much of this unnecessary. |
| </li> |
| </ol> |
| </p> |
| </answer> |
| </entry> |
| <entry id="website_3" category="Website"> |
| <question>What is the CVS info for the webtools website?</question> |
| <answer> |
| The WTP website is located in the cvs root for the Eclipse website in |
| the www/webtools folder.<br /><br /> |
| server : dev.eclipse.org<br/> |
| path : /cvsroot/org.eclipse |
| </answer> |
| </entry> |
| <entry id="website_4" category="Website"> |
| <question>Why do I see a javax.net.ssl.SSLHandshakeException when building the website?</question> |
| <answer> |
| The WTP website requires access to Eclipse's bugzilla system in order to build the plans |
| section. If you see the following error:<br/> |
| <br/> |
| javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: |
| No trusted certificate found<br/> |
| <br/> |
| when building the site and using a Sun JRE you should update your JRE to at least |
| Sun JRE 1.4.2_09. |
| </answer> |
| </entry> |
| <entry id="general_1" category="General"> |
| <question>Who do we contact in order to get commiter passwords reset?</question> |
| <answer> |
| You need to contact the Eclipse webmaster at <a href="mailto:webmaster@eclipse.org">webmaster@eclipse.org</a>. |
| </answer> |
| </entry> |
| <entry id="general_2" category="General"> |
| <question>How do I change my dev.eclipse.org password?</question> |
| <answer> |
| You can change your password using the committer tools available at <a href="https://dev.eclipse.org/committers/">https://dev.eclipse.org/committers/</a>. |
| </answer> |
| </entry> |
| <entry id="general_3" category="General"> |
| <question>How can I set up a workspace for WTP development/extension?</question> |
| <answer> |
| <p> |
| There are three ways you can set up a workspace to either develop WTP or |
| develop on the WTP base: |
| <ol> |
| <li> |
| Install WTP and check-out only the plug-ins you are interested in, from the Branch you are interested in. |
| This method is useful if you are only working with a subset of |
| WTP functionality or extending WTP. For a quick connection, paste |
| <b>:pserver:anonymous@dev.eclipse.org:/cvsroot/webtools</b> into your CVS Repositories view. |
| <ol> |
| <li> |
| Download and install the WTP build you want to work with |
| from the <a href="http://download.eclipse.org/webtools/downloads/" target="_top">WTP downloads page</a>. |
| </li> |
| <li> |
| Create a new workspace using your installed version of WTP. |
| </li> |
| <li> |
| Check-out any plug-ins you need to modify from the WTP CVS repository. |
| </li> |
| </ol> |
| </li> |
| <li> |
| Check-out the latest version of all the WTP plug-ins using the WTP project set. (This will extract |
| all of the WTP plug-ins from the HEAD branch.) This method is useful if you want the |
| most up-to-date version of the WTP plug-ins. |
| <ol> |
| <li> |
| Download the WTP team project set file from <a href="http://www.eclipse.org/webtools/development/team_project_set/wtp.psf" target="_top">http://www.eclipse.org/webtools/development/team_project_set/wtp.psf</a>. |
| </li> |
| <li> |
| In your Eclipse workbench, select File->Import->Team Project Set. Select the WTP |
| team project set file you downloaded and click Finish.<br/> |
| <br/> |
| *note: It may take a while for |
| all the WTP plug-ins to be checked-out into your workspace. |
| </li> |
| </ol> |
| </li> |
| <li> |
| Check-out WTP plug-in Versions from a specific build. This method is useful |
| if you want to extend or test a specific version of WTP.<br/> |
| <br/> |
| *note: this method requires that you have the Eclipse Releng plug-in installed. For information |
| about this plug-in see the FAQ entry <a href="#cvs_4">Is there a tool for releasing changes?</a>. |
| <ol> |
| <li> |
| Launch Eclipse and create a simple project in your workspace. |
| </li> |
| <li> |
| On the <a href="http://download.eclipse.org/webtools/downloads/" target="_top">WTP downloads page</a>, |
| select the WTP build for which you want to check-out all the plug-ins. On the |
| top of the page for the specific download, select map files and save the |
| file as wtp.map in your simple project.<br/> |
| <br/> |
| *note: you may need to refresh your workspace for the file to be visible in it. |
| </li> |
| <li> |
| Right click on the map file and select <b>Team > Load Map projects</b>. The plug-in versions from the |
| build will be checked-out into your workspace.<br/><br/> |
| *note: It may take a while for all of the WTP plug-ins to be downloaded to your workspace. |
| </li> |
| </ol> |
| </li> |
| </ol> |
| <br/> |
| All three options require compiling some or all of WTP within your workspace, so your Plug-in Development Target |
| Platform should contain the corresponding WTP prerequisites. |
| </p> |
| </answer> |
| </entry> |
| <entry id="source_1" category="Source Code"> |
| <question>What copyrights should we use? </question> |
| <answer> |
| <p>The copyright statement takes one of these two forms, differing only in the year stated on the first line of text.<br/> |
| IBM copyrights below are examples only and won't apply to everyone in the community. New files <b>you</b> commit should be |
| attributed to yourself or your employer according to your Committer Agreement and any employment agreements you may operate |
| under.</p> |
| <ul> |
| <li>If the file's year of invention and last year of modification are the same.<br/> |
| Example:<br/> |
| /*******************************************************************************<br/> |
| * Copyright (c) 2005 IBM Corporation and others.<br/> |
| * All rights reserved. This program and the accompanying materials<br/> |
| * are made available under the terms of the Eclipse Public License v1.0<br/> |
| * which accompanies this distribution, and is available at<br/> |
| * http://www.eclipse.org/legal/epl-v10.html<br/> |
| *<br/> |
| * Contributors:<br/> |
| * IBM Corporation - initial API and implementation<br/> |
| *******************************************************************************/ |
| </li> |
| <li>If the file's year of invention and most recent year of modification are |
| different...<br/> |
| Example:<br/> |
| /*******************************************************************************<br/> |
| * Copyright (c) 2001,2005 IBM Corporation and others.<br/> |
| * All rights reserved. This program and the accompanying materials<br/> |
| * are made available under the terms of the Eclipse Public License v1.0<br/> |
| * which accompanies this distribution, and is available at<br/> |
| * http://www.eclipse.org/legal/epl-v10.html<br/> |
| * <br/> |
| * Contributors:<br/> |
| * IBM Corporation - initial API and implementation<br/> |
| *******************************************************************************/ |
| </li> |
| Commits should always be covered under the EPL. |
| </ul> |
| </answer> |
| </entry> |
| <entry id="source_2" category="Source Code"> |
| <question>Is there a tool to update the copyright?</question> |
| <answer> |
| <B>org.eclipse.releng.tools </B>plug-in from |
| <a href="http://www.eclipse.org/downloads/index.php">Eclipse download site</a> |
| allows you to fix copyrights. |
| </answer> |
| </entry> |
| <entry id="source_3" category="Source Code"> |
| <question>What are the package naming conventions?</question> |
| <answer> |
| See the <a href="../development/guidelines/naming-conventions.html">WTP project naming |
| conventions</a> |
| </answer> |
| </entry> |
| <entry id="cvs_2" category="Build/CVS"> |
| <question>How do I add my plug-in to the WTP CVS repository?</question> |
| <answer> |
| <ol> |
| <li>On your plug-in project select <B>Team->Share Project...</B> context menu.</li> |
| <li>Choose existing repository location (or create a new one if you haven't) for |
| <B>dev.eclipse.org:/cvsroot/webtools</B> |
| </li> |
| <li>On the next page, if you know exactly where the plug-in should be located in the |
| repository, then select the "Use specified module name" radio button and |
| type in the full path. However, to be safe, it's recommended browsing the repository |
| to obtain the correct path, and then adding the module name. Here is an example:<br/> |
| <br/> |
| Select the "Use an existing module".<br/> |
| Browse and then select the folder where you want your new plug-in to reside.<br/> |
| <br/> |
| <img border="0" src="images/shareProject1.gif" width="485" height="602"/><br/> |
| <br/> |
| Notice that the text field is filled in with the path. Reselect the "Use |
| specified module name:" radio button, and append your plug-in's name.<br/> |
| <br/> |
| <img border="0" src="images/shareProject2.gif" width="486" height="602"/> |
| </li> |
| </ol> |
| </answer> |
| </entry> |
| <entry id="cvs_3" category="Build/CVS"> |
| <question>Where can I find more information about CVS?</question> |
| <answer> |
| The <a href="http://dev.eclipse.org/viewcvs/index.cgi/?cvsroot=WebTools_Project">WTP |
| CVS respository page</a> contains links to useful CVS documentation including how to |
| use Eclipse with CVS. |
| </answer> |
| </entry> |
| <entry id="cvs_4" category="Build/CVS"> |
| <question>Is there a tool for releasing changes?</question> |
| <answer> |
| Yes. The releng tool plug-in is available from the <a href="http://download.eclipse.org/eclipse/downloads" target="_top">Eclipse Project download page</a>. Each version |
| of Eclipse contains its own releng tool plug-in. Select the version of Eclipse you're |
| using. The releng tool plug-in is found at the bottom of the page. |
| </answer> |
| </entry> |
| <entry id="cvs_5" category="Build/CVS"> |
| <question>How do I release my changes?</question> |
| <answer> |
| <ol> |
| <li> |
| Commit your changes to the CVS repository. (For information about |
| CVS and committing see the FAQ entry <a href="#cvs_3">Where can I find more information about CVS?</a>). |
| Commits for bug fixes should contain the bug number and summary for future reference, e.g. "[269600] Improve Code Folding performance". |
| </li> |
| <li> |
| Check-out the appropriate releng project using the correct branch from the CVS repository. Each WTP subproject has its own releng project, |
| containing the map files for its features and bundles. |
| </li> |
| <li> |
| <b> |
| *note: It is strongly recommended that you use the releng tool to release |
| your changes. |
| </b> |
| <p> |
| You now have to tag your source files and update the corresponding map entries. |
| Although you can do this manually, it is much easier and less error prone to use |
| the releng tool. (See FAQ entry <a href="#cvs_4">Is there a tool for releasing |
| changes?</a>) |
| </p> |
| <ol> |
| <li> |
| Select the plug-in you want to release. Right click on it and select Team->Release as shown below.<br /><br /> |
| <img src="images/releasemenu.gif"/> |
| </li> |
| <li> |
| Select the releng project as the map project. Click Next. |
| </li> |
| <li> |
| If not already selected, select the plug-ins you want to release. Click Next. |
| </li> |
| <li> |
| The page displays the changes between the last released version of the plug-in |
| and what is currently in your workspace. Anything that is changed locally and not checked into the |
| CVS branch will not be properly tagged. Review the changes. If everything is correct, click Next. |
| </li> |
| <li> |
| Enter the tag you want to use to release the changes. WTP uses tags of the form |
| v<i>YYYYMMDDHHMM</i>, based on the tagging time as expressed in |
| <a href="http://time.gov/timezone.cgi?UTC/s/0">Universal Coordinated Time</a>. |
| Click Next. |
| </li> |
| <li> |
| The page displays the changes to the map files. Review the changes. If everything |
| is correct, click Next. |
| </li> |
| <li> |
| Enter a comment for the release operation and click Finish. The comment used |
| will be displayed with the map file as part of the build output, so it's suggested |
| to use a combination of the commit comments for the fixes being released. |
| </li> |
| </ol> |
| </li> |
| </ol> |
| </answer> |
| </entry> |
| <entry id="cvs_6" category="Build/CVS"> |
| <question>What do I need to do before releasing changes?</question> |
| <answer> |
| <p> |
| It depends. If you're releasing an isolated fix, you're probably safe to run the |
| JUnit tests for the plug-in and, if all pass, release your fix. If you're making |
| a breaking provisional API change (remember, you cannot make breaking API changes) |
| you should announce the change to the WTP dev list advising |
| what has changed, why, and how existing consumers of the provisional API can |
| adapt their plug-ins to the change. |
| </p> |
| <p> |
| It is also good practice to use a current WTP development build when making |
| changes so as prevent compilation failures. Catching compilation or unit test |
| failures is a poor use of the build system's processing time. |
| </p> |
| </answer> |
| </entry> |
| <entry id="cvs_7" category="Build/CVS"> |
| <question>How do I add a new plug-in to WTP?</question> |
| <answer> |
| <p> |
| <b>Follow this procedure closely. Mistakes will likely cause a build breakage.</b><br/> |
| There are three tasks to add a new plug-in to WTP: |
| <ol> |
| <li> |
| Commit your new plug-in to the CVS repository. See <a href="#cvs_2">How do I add my plug-in to the WTP CVS repository?</a> |
| </li> |
| <li> |
| <p> |
| Add your plug-in to the appropriate feature. Features are located under the |
| subproject's assembly component. For example, for WST you can find features |
| at wst/components/assembly/features. |
| </p> |
| <p> |
| A feature entry will look like the following:<br /> |
| <br /> |
| <plugin<br /> |
|     id="org.eclipse.wst.common.uriresolver"<br /> |
|     download-size="0"<br /> |
|     install-size="0"<br /> |
|     version="0.0.0"/><br /> |
| </p> |
| <p> |
| After you've added your plug-in to the feature, commit the changes |
| and release the feature. |
| </p> |
| </li> |
| <li> |
| Add your plug-in to the appropriate map file. Map files are located in the |
| releng component. A map file entry will look like the following:<br /> |
| <br/> |
| plugin@org.eclipse.wst=v20050718_2336,:pserver:anonymous@dev.eclipse.org:/home/webtools,,wst/components/assembly/plugins/org.eclipse.wst<br /> |
| <br /> |
| After updating the map file commit it to the repository. |
| </li> |
| <li> |
| <p> |
| Your plug-in is now in the repository, included in a feature, and included |
| in a map. Now release your plug-in. |
| </p> |
| </li> |
| <li><p>Send a note to the WTP <a href="mailto:wtp-releng@eclipse.org">release engineering</a> mailing list mentioning the plug-in's addition. It is possible that the build process itself may require updates to accommodate the addition, such as touchups to releng-specific BVTs.</p> |
| </li> |
| </ol> |
| </p> |
| </answer> |
| </entry> |
| <entry id="cvs_8" category="Build/CVS"> |
| <question>How do I jar my plug-in?</question> |
| <answer> |
| <p> |
| First of all, jarring is not an option for every plug-in. If your plug-in contains |
| multiple jars you can't jar your plug-in. |
| </p> |
| <p> |
| There are a three steps to jarring your plug-in: |
| <ol> |
| <li> |
| Update your plug-in's build.properties file to include the source.. and |
| output.. keys as well as "." for bin.includes and src.includes as follows:<br /> |
| <br /> |
| source.. = src/<br /> |
| output.. = bin/<br /> |
| bin.includes = plugin.xml,\<br /> |
|                META-INF/,\<br /> |
|                .,\<br /> |
|                plugin.properties,\<br /> |
|                about.html<br /> |
| src.includes = exsd/,\<br /> |
|                .,\<br /> |
|                build.properties<br /> |
| </li> |
| <li> |
| Update your plug-in's manifest (MANIFEST.MF) by removing the line beginning with "Bundle-ClassPath". |
| </li> |
| <li> |
| Update the feature entry for your plug-in to include the unpack=false attribute.<br /> |
| <br /> |
| <plugin<br /> |
|     id="org.eclipse.wst.common.uriresolver"<br /> |
|     download-size="0"<br /> |
|     install-size="0"<br /> |
|     version="0.0.0"<br /> |
|     unpack="false"/> |
| </li> |
| </ol> |
| </p> |
| </answer> |
| </entry> |
| <entry id="cvs_9" category="Build/CVS"> |
| <question>How do I delete folders from the CVS repository?</question> |
| <answer> |
| <p> |
| First of all, folders should not normally be deleted from the CVS repository. The |
| repository is meant to contain the history of WTP development. That said, you may |
| have reason to delete a folder such as you committed a folder with the incorrect name, |
| or committed to the wrong location. In these cases: |
| <ol> |
| <li> |
| Delete the content from the folder. The content will show up in the Web view |
| under the attic folder. |
| </li> |
| <li> |
| Commit an obsolete.txt file in the folder. The file should contain the reasons |
| why the folder is obsolete. |
| </li> |
| <li> |
| Request that the Eclipse webmaster delete the folder. Requests can be made by sending |
| the webmaster an e-mail to <a href="mailto:webmaster@eclipse.org">webmaster@eclipse.org</a>. |
| </li> |
| </ol> |
| </p> |
| </answer> |
| </entry> |
| <entry id="source_4" category="Source Code"> |
| <question>What comment should I use when declaring public provisional API?</question> |
| <answer> |
| <p> |
| The following comment should be placed in each provisional API class description:<br /> |
| <br /> |
| * <p><br /> |
| * <b>Note:</b> This class/interface is part of an interim API that is still under development and expected to<br /> |
| * change significantly before reaching stability. It is being made available at this early stage to solicit feedback<br /> |
| * from pioneering adopters on the understanding that any code that uses this API will almost certainly be broken<br /> |
| * (repeatedly) as the API evolves.<br /> |
| * </p> |
| </p> |
| <p> |
| See the WST <a href="http://dev.eclipse.org/viewcvs/index.cgi/wst/components/server/plugins/org.eclipse.wst.server.core/servercore/org/eclipse/wst/server/core/IModule.java?rev=1.12&cvsroot=WebTools_Project&content-type=text/vnd.viewcvs-markup" target="_top">Server core plug-in</a> for an example. |
| </p> |
| </answer> |
| </entry> |
| <entry id="source_5" category="Source Code"> |
| <question>What is the proper use of Javadoc @since tags?</question> |
| <answer> |
| <p> |
| When you add a package or class to the API, include a single package or class level @since tag, e.g. @since 1.0. |
| </p> |
| <p> |
| When you add a method to an existing API class, add a method level @since tag. |
| </p> |
| <p> |
| These rules minimize the number of @since tags you need to include. The |
| reference for the use of Javadoc in general is available |
| <a href="http://java.sun.com/j2se/javadoc/writingdoccomments/ " target="_top">here</a>. |
| </p> |
| </answer> |
| </entry> |
| <entry id="general_4" category="General"> |
| <question>What is the correct usage of severity when opening a WTP bug?</question> |
| <answer> |
| <p> |
| Although this is somewhat of a judgement call, you should use the standard |
| definitions found <a href="https://bugs.eclipse.org/bugs/bug_status.html#bug_severity" target="_top">here</a>. |
| </p> |
| <p> |
| Component owners should double check open Blocker/Critical/Major bugs to |
| make sure they are accurately described. |
| </p> |
| <p> |
| Although a user may feel strongly about their favourite bug, we should still |
| classify it correctly. We do have some leeway in assigning it a priority, |
| i.e. if we feel that a bug should be fixed, we can up its priority. P1 should |
| be reserved for release-defining functions, .i.e we stop ship if P1's are not |
| fixed. |
| </p> |
| </answer> |
| </entry> |
| <entry id="general_components" category="General"> |
| <question> |
| How do I help users assign WTP bugs to the correct component? |
| </question> |
| <answer> |
| When users assign a WTP bug to the wrong component, you should |
| assign it to the correct component and paste in the following |
| message as a comment: |
| <pre> |
| Thank you for reporting this bug. I have assigned to the correct component. |
| For guidance on how to select the correct component in future bug reports, please refer to: |
| https://bugs.eclipse.org/bugs/describecomponents.cgi?product=Web+Tools |
| </pre> |
| </answer> |
| </entry> |
| <entry id="general_targets" category="General"> |
| <question> |
| What do I do if I don't see the right target milestone for a bug? |
| </question> |
| <answer> |
| Check with your subproject lead, as they usually have the Bugzilla edit privileges to add them. |
| </answer> |
| </entry> |
| <entry id="general_newbugs" category="General"> |
| <question> |
| How do I know when new bugs are reported? |
| </question> |
| <answer> |
| Your Bugzilla <a href="https://bugs.eclipse.org/bugs/userprefs.cgi">Preferences</a> link (see the bottom of any Bugzilla page once logged in) allows you |
| to specify a 'watch list' of user emails to be copied on. Most components have an inbox address |
| that you can watch. You can also query Bugzilla with the correct inbox address as the Assignee and |
| subscribe to the results as an RSS feed from the results page using the 'Feed' link at the bottom. |
| </answer> |
| </entry> |
| </faq> |
