Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "CDT/policy"

< CDT
(Using API Tooling)
(typos in API tooling section)
Line 104: Line 104:
 
All committers and contributors should enable API Tooling when writing patches for CDT.  The procedure takes less than 30 seconds:
 
All committers and contributors should enable API Tooling when writing patches for CDT.  The procedure takes less than 30 seconds:
  
# Download the official CDT release you are building a patch against (if you are building a patch for CDT HEAD or CDT 8.0.1, you need CDT 8.0 from [http://download.eclipse.org/tools/cdt/builds/8.0.0/I.I201106081058/index.html here]
+
# Download the official CDT release you are building a patch against (if you are building a patch for CDT HEAD or CDT 8.0.1, you need CDT 8.0 from [http://download.eclipse.org/tools/cdt/builds/8.0.0/I.I201106081058/index.html here])
 
# Unzip it in some directory (e.g, CDT8.0/)
 
# Unzip it in some directory (e.g, CDT8.0/)
 
# In eclipse go to Preferences->Plug-in Development->API Baselines
 
# In eclipse go to Preferences->Plug-in Development->API Baselines
# Press the Add Baselines... button
+
# Press the "Add Baseline..." button
 
# Name your new baseline (e.g, CDT8.0)
 
# Name your new baseline (e.g, CDT8.0)
 
# Choose the directory of point #2 and press OK
 
# Choose the directory of point #2 and press OK

Revision as of 21:17, 27 June 2011

Code Formatting

  • It is recommended to use default "Eclipse" code formatting for Java for new code.
  • It is recommended to preserve formatting of old code when making patches

Eclipse Java Errors/Warnings

It is strongly recommended for cdt plugins to override default compiler error/warning and use project specific errors/warnings. Projects should have the following customizations:

  • Method with a constructor name - Error
  • Assignment has no effect - Error
  • Possible accidental boolean assignment - Error
  • finally does not complete normally - Error
  • Using a char array in string concatenation - Error
  • Null pointer access - Error
  • Potential null pointer access - Warning
  • Unused Import - Error

All commiters and contributors submitting patches should enable API tooling by setting target baseline platform. Do not commit code with API errors.

Patches with errors listed above including API errors will not be accepted without corrections.

Committers who wish to keep a plugin warning-free should update the project as follows. These steps turns warnings into errors and leaves everything else in the ignore state. In other words, the idea is not to turn everything into an error, just the things that are set to generate a warning.

  1. Open project properties > Java Compiler > Errors/Warnings
    1. Turn on Enable project specific settings
    2. Turn on Annotations > Suppress optional errors with '@SuppressWarnings' (new pref in Helios)
  2. Open .setings/org.eclipse.jdt.core.prefs in a text editor and do a find&replace of "=warning" to "=error" (use Replace All)
  3. Turn on project properties > Plug-in Development > API Errors/Warnings > Use project settings
  4. Open .settings/org.eclipse.pde.api.tools.prefs in a text editor and do a find&replace of "=Warning" to "=Error" (use Replace All; 'W' and 'E' must be uppercase)
  5. Turn on project properties > Plug-in Development > Plug-in Manifest Compiler > Use project settings
  6. Open .settings/org.eclipse.pde.prefs in a text editor and do a find&replace of "=1" to "=0" (use Replace All)

Copyright

Use eclipse copyright header: http://www.eclipse.org/legal/copyrightandlicensenotice.php. Here is an example:

/*******************************************************************************
 * Copyright (c) 2008, 2010 XYZ Corp. and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *    Jane Doe (XYZ Corp.) - initial API and implementation
 *    John Smith (ABC Enterprises) - Multi-gadget support for the widget (bug 654321)
 *******************************************************************************/ 

Normally contributors line is added for significant changes in the file.

API

There are 3 types of API: Public API, Provisional API and Internal API (aka Private API, aka non API). Public API is what all client should use, it suppose to be documented (javadoc) and should not change much from version to version. If major version of the plugin changed it may contain API breakage. If minor version of the plugin changed it may contain API extensions (non-breaking changes). There is also some policies about changing API between milestone builds. Provisional API is a public API in making. It does not have to follow versioning and other rules of public API, but other than that, it can be threated as public.

Examples API breaking change:

  • Adding a method in interface
  • Changing method signature
  • Changing private visibility to any other

Examples of API extensions:

  • Adding new extension point
  • Changing visibility from protected to public
  • Adding method in a class

So here is what considered Internal API vs Public vs Provisional for CDT

  • Internal API
    • packages with name *.internal.*, *.examples.*
    • test projects, releng projects and feature projects
    • packages which are not exported or X-exported (i.e. not exported as public)
    • non-java code (i.e. native C code)
    • private and package private classes and members
  • Provisional API
    • packages with names *.provisional*
    • class that are marked EXPERIMENTAL and all its members
 EXPERIMENTAL. This class or interface has been added as part
 of a work in progress. There is no guarantee that this API will work or that
 it will remain the same.
  • Public API
    • everything which is not internal or provisional and
      • has public or protected java visibility
      • in public exported package
    • public API class or interface can also have some usage exceptions:
      • classes and members marked @noreference in the javadoc comment cannot be used and not considered public API even if they have public visibility
      • classes and interfaces that are marked as @noextend should not be extended
      • interfaces that are marked @noimplement should not be implemented

See also Evolving Java-based APIs.

Note: you can still use internal API is you want to, if java visibility allows you (even if it does not, you can hack it, using reflection). The only problem with this approach is that internal API can be changed without notice or trace, so you would have hard time making your code compile or run with new version of the tool. The best approach in this case to submit a bug asking to create an API for functionality you are looking for.

Using API Tooling

All committers and contributors should enable API Tooling when writing patches for CDT. The procedure takes less than 30 seconds:

  1. Download the official CDT release you are building a patch against (if you are building a patch for CDT HEAD or CDT 8.0.1, you need CDT 8.0 from here)
  2. Unzip it in some directory (e.g, CDT8.0/)
  3. In eclipse go to Preferences->Plug-in Development->API Baselines
  4. Press the "Add Baseline..." button
  5. Name your new baseline (e.g, CDT8.0)
  6. Choose the directory of point #2 and press OK
  7. Make sure the new baseline is the selected one.


Once this is done, a full build will be triggered. After that, any changes that doesn't follow API rules will be show as an error.

Javadoc

All public API classes and interfaces must have meaningful javadoc header, as well as all public API members.

Contributing to CDT

See CDT/contributing

Applying the Patch

  • Assign bug to yourself
  • Set target milestone field to release in which patch would be applied, If it is applied in two branches set target milestone to maintenance branch
  • Code inspect the patch, apply and test
  • Commit the patch
  • Set the iplog as follows:
    • to '-' if the patch came from a committer
    • to '+' if the patch came from a non-committer.
  • If the patch is >= 250 lines, it must be submitted for IP review, i.e. CQ in IPZilla. See Development_Resources/Automatic_IP_Log
  • Check that all non-committed patches are marked as obsolete
  • Change bug state to fixed. Check again that you set milestone field.
  • Add a comment about where it was fixed (branches) and related notes

Committing Code

  • API changes have to be discussed in cdt-dev mailing list before commiting
  • When development reaches cycle where release candidates are built, letter in cdt-dev should be sent for every commit you are making
  • Have a bug associated with every commit, bug number at the begging of commit comment in form of
 Bug 12345 fixed that, added this
  • Have a patch for commit attached to the pr (optional but encouraged)
  • Optional request a reviewer bug setting review flag to ? and flag comment to person address (or inbox)

How to add a new feature

  • Create a feature project
  • Copy build.properties, epl-v10.html, feature.properties, feature.xml, license.html from another cdt feature plugin
  • Open in feature editor and modify all feature specific details including plugin list
  • Add it org.eclipse.cdt.releng/buildsite.xml (see how other are done)
  • Add in maps org.eclipse.cdt.releng/maps/cdt.map

How to add a new plugin

  • Create a new plugin plugin
  • Version should be like 1.0.0.qualifier
  • Edit name and vendor. Externalize string. Bundle-Vendor = Eclipse CDT
  • Add your plugin to a feature
  • Edit org.eclipse.cdt.releng/build.xml, add call to "tagone" target with your plugin path. See examples in the file.
  • Open project properties Java Compiler -> Error and Warnings. Check "Enable project specific settings". Go through list of warnings and set some to errors (see above list of recommended settings). Some people prefer zero warning tolerance, in this case all of them should be errors and no warnings.
  • Add in maps org.eclipse.cdt.releng/maps/cdt.map
  • Make sure all packages are exported (or x-exported). See http://wiki.eclipse.org/Export-Package
  • Check in all changed plugins

Version Numbering

See Eclipse Version Numbering Guildlines

Bugs Workflow

For creating and managing bugs see http://wiki.eclipse.org/CDT/Bugs

Back to the top