Update the Committer FAQ
diff --git a/faq/CommitterFAQ.xml b/faq/CommitterFAQ.xml
index b5d7839..e108ef6 100644
--- a/faq/CommitterFAQ.xml
+++ b/faq/CommitterFAQ.xml
@@ -5,20 +5,27 @@
xsi:schemaLocation="http://www.eclipse.org/webtools/faq schemas/faq.xsd"
name="wtp committer faq">
<category name="General"/>
- <category name="Build/CVS"/>
+ <category name="Build/Git"/>
<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>
+ <entry id="git_1" category="Build/Git">
+ <question>Where are the source code repositories for the webtools project?</question>
<answer>
- server : dev.eclipse.org<br/>
- path : /cvsroot/webtools
+ WTP's source code repositories are hosted on Eclipse.org and accessed through Gerrit. The following pages allow browsing the repositories and list the current cloning URLs at the bottom of the respective pages.
+ <a href="https://git.eclipse.org/c/gerrit/webtools-common/webtools.common.git">webtools.common</a><br/>
+ <a href="https://git.eclipse.org/c/gerrit/dali/webtools.dali.git">webtools.dali</a><br/>
+ <a href="https://git.eclipse.org/c/gerrit/jeetools/webtools.javaee.git">webtools.javaee</a><br/>
+ <a href="https://git.eclipse.org/c/gerrit/jsdt/webtools.jsdt.git">webtools.jsdt</a><br/>
+ <a href="https://git.eclipse.org/c/jsf/webtools.jsf.git">webtools.jsf</a><br/>
+ <a href="https://git.eclipse.org/c/gerrit/servertools/webtools.servertools.git">webtools.servertools</a><br/>
+ <a href="https://git.eclipse.org/c/gerrit/sourceediting/webtools.sourceediting.git">webtools.sourceediting</a><br/>
+ <a href="https://git.eclipse.org/c/gerrit/webservices/webtools.webservices.git">webtools.webservices</a><br/>
</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/>
+ 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>
@@ -27,86 +34,54 @@
<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>
+ The web site is itself hosted within a git repository, whose page can be found <a href="https://git.eclipse.org/c/www.eclipse.org/webtools.git/">here</a>. Updates pushed to it are not made live immediately, but periodically published within a matter of minutes.
</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>
+ <question>How do I change my dev.eclipse.org password?</question>
<answer>
- You need to contact the Eclipse webmaster at <a href="mailto:webmaster@eclipse.org">webmaster@eclipse.org</a>.
+ You can change your password using <a href="http://accounts.eclipse.org">accounts.eclipse.org</a>. Use the menu to Edit your Account and then go to the Account Settings tab.
</answer>
</entry>
<entry id="general_2" category="General">
- <question>How do I change my dev.eclipse.org password?</question>
+ <question>Who do we contact in order to get my password reset?</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>.
+ Use the <em>How do I reset my dev.eclipse.org password?</em> link at the sign-in page for
+ <a href="http://accounts.eclipse.org">accounts.eclipse.org</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
+ There are multiple 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.
+ The most popular method is to 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.
+ WTP functionality or extending WTP.
<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>.
+ Download and install a working WTP build
+ from the <a href="https://wiki.eclipse.org/WTP_FAQ#How_do_I_install_WTP.3F" target="_top">instructions</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.
+ Clone the relevant git repository (see <a href="#git_1">the list</a>).
+ </li>
+ <li>
+ The projects in our repositories are IDE-first, and include the .project files so
+ they can be used immediately as Plug-in and Feature projects. Import the intended
+ project into your workspace from the Git Repositories View.
</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
@@ -129,7 +104,7 @@
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>.
+ about this plug-in see the FAQ entry <a href="#git_3">Is there a tool for releasing changes?</a>.
<ol>
<li>
Launch Eclipse and create a simple project in your workspace.
@@ -149,6 +124,7 @@
</li>
</ol>
</li>
+ -->
</ol>
<br/>
All three options require compiling some or all of WTP within your workspace, so your Plug-in Development Target
@@ -159,39 +135,50 @@
<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>
+ <p>Commits should always be covered under the EPL.</p>
+ <p>The copyright statement required in each source file takes one of these two forms, differing only in the year stated on the first line of text.<br/>
+ New files <b>you</b> commit are copyrighted by yourself or your employer according to your Eclipse Contributor Agreement and any employment agreements you may operate
+ under, and licensed to everyone under EPL 2.0--including to WTP.</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/>
- *******************************************************************************/
+<pre>
+/*******************************************************************************
+ * Copyright (c) 2021 <original author>
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License 2.0
+ * which accompanies this distribution, and is available at
+ * https://www.eclipse.org/legal/epl-2.0/
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ *
+ * Contributors:
+ * <original author> - initial API and implementation
+ *
+ *******************************************************************************/
+</pre>
+
</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/>
- *******************************************************************************/
+<pre>
+/*******************************************************************************
+ * Copyright (c) 2021, <modification year> <original author> <and others (if a new person is making modifications)>
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License 2.0
+ * which accompanies this distribution, and is available at
+ * https://www.eclipse.org/legal/epl-2.0/
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ *
+ * Contributors:
+ * <original author> - initial API and implementation
+ * <additional author if new> - bug reference or description of change
+ *
+ *******************************************************************************/
+</pre>
</li>
- Commits should always be covered under the EPL.
</ul>
</answer>
</entry>
@@ -199,8 +186,9 @@
<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.
+ <a href="https://download.eclipse.org/eclipse/downloads/">Eclipse build download site</a>
+ allows you to fix copyrights. It should not needed as developers should
+ check the top of every modified file for the current year before committing/merging changes.
</answer>
</entry>
<entry id="source_3" category="Source Code">
@@ -210,109 +198,28 @@
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>
+ <entry id="git_2" category="Build/Git">
+ <question>Where can I find more information about Git?</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>
+ <a href="https://wiki.eclipse.org/WTP_Git_Migration_Home">This wiki page</a> was used as a reference point when migrating WTP from CVS to Git.
</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">
+ <entry id="git_3" 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.
+ Not in the traditional sense. We use
+ <a href="https://ci.eclipse.org/webtools">ci.eclipse.org/webtools</a>
+ for Continuous Integration. It does contain a Job for publishing builds for
+ milestones and releases.
</answer>
</entry>
- <entry id="cvs_5" category="Build/CVS">
+ <entry id="git_4" 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>
+ Releases are performed by members of the releng team, using the output of the WTP-CI_master job.
</answer>
</entry>
- <entry id="cvs_6" category="Build/CVS">
+ <entry id="git_5" category="Build/CVS">
<question>What do I need to do before releasing changes?</question>
<answer>
<p>
@@ -330,7 +237,7 @@
</p>
</answer>
</entry>
- <entry id="cvs_7" category="Build/CVS">
+ <entry id="git_6" category="Build/CVS">
<question>How do I add a new plug-in to WTP?</question>
<answer>
<p>
@@ -338,15 +245,15 @@
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>
+ Add your new plug-in to the correct git repository. See <a href="#git_1">Where are the source code repositories for the webtools project?</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>
+ Add your plug-in to the appropriate feature.xml. Features are typically in their own directory.
+ For example, for Common you can find features
+ under the top-level <code>features</code> <a href="https://git.eclipse.org/c/gerrit/webtools-common/webtools.common.git/tree/features">directory</a>.
+ <b>Your plug-in will need its requirements to be provided in the feature or that feature's dependencies.</b>
+ </li>
+ <li>
A feature entry will look like the following:<br />
<br />
<plugin<br />
@@ -354,102 +261,24 @@
    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.
+ Create a pom.xml for the new plug-in. Use another plug-in from the same feature for guidance.
</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>
+ After you've added your plug-in to the feature, commit and push the changes.
+ </li>
+ <li>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.
</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>It's best to avoid any "provisional APIs" for the sake of future binary compatibility. Make it public or leave it private.
+ </p>
<p>
The following comment should be placed in each provisional API class description:<br />
<br />
@@ -486,8 +315,9 @@
<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>.
+ definitions found <a href="https://bugzilla.readthedocs.io/en/5.0/using/understanding.html" target="_top">here</a>.
</p>
+ <p>CRITICAL severity is typically reserved for defects that either crash the IDE or irretrievably destroy the user's data.</p>
<p>
Component owners should double check open Blocker/Critical/Major bugs to
make sure they are accurately described.
@@ -497,7 +327,7 @@
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.
+ fixed.
</p>
</answer>
</entry>
@@ -507,26 +337,26 @@
</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:
+ assign it to the correct component, resetting it to the default assignee,
+ 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
+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?
+ What do I do if I don't see the right Version to report a bug against, or target milestone for marking a bug fixed?
</question>
<answer>
- Check with your subproject lead, as they usually have the Bugzilla edit privileges to add them.
+ Check with your project lead, as they usually have the Bugzilla privileges to add them using the COMMITTER TOOLS panel on <a href="https://accounts.eclipse.org">accounts.eclipse.org</a>.
</answer>
</entry>
<entry id="general_newbugs" category="General">
<question>
- How do I know when new bugs are reported?
+ How can 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
