Difference between revisions of "CDT/policy"

Revision as of 16:01, 26 April 2020

Code Formatting

These are the coding style recommendations that are in place with project setting. They are enforced by the build process and auto-save actions in Eclipse.

• Preserve formatting and style of old code when making patches
• Use default "Eclipse" code formatting for Java for new code
• Organize Imports action on save
• It is recommended to use code blocks (curly brackets) for for/while/do/if statement bodies, with the exception of simple terminating statements, i.e. "if (a) return;"

Eclipse Java Errors/Warnings

All CDT plugins override default compiler error/warning and use project specific errors/warnings. This enforced by the build process.

All committers 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.

Evolving Warning and Error settings

The warnings and error settings can and should be evolved as needed. For example, a bundle with no warning may want to ensure no new warnings are introduced and should change the project specific settings to upgrade those warnings to errors as needed. This change may require changes to the to code cleanliness checks that ensure warnings/errors are at the correct level.

Copyright

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

/********************************************************************************
 * Copyright (c) {date} {owner}[ and others]
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0.
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * Contributors:
 *   {name} - initial API and implementation
 ********************************************************************************/

A contributors line can be added for significant changes in the file but this is optional.

API

The Eclipse CDT project follows the same guidelines and policies as the Eclipse Platform project, with exceptions noted below. See [[Eclipse/API_Central|Eclipse API Central] for more details.

Note: you can still use internal API if 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 the internal API can be changed without notice or trace, if this happened, you would have a hard time making your code compile or run with new version of the tool. The best approach in this case is to submit a bug asking to create an API for functionality you are looking for.

Deprecating and Deleting API

The Eclipse CDT project follows the same guidelines and policies as the Eclipse Platform project. See Deprecation Policy. The changes to the policy are:

1. Removal of any Eclipse CDT API requires approval from the Eclipse CDT Committers.
2. Announcement must be made on cdt-dev mailing list - it can be additionally made to cross-project-issues-dev mailing list if there is concern that the impact of such removal would affect other Eclipse projects.
3. API Changes should be listed in the New and Noteworthy wiki page.
4. API removals and API breakages, actual or planned, should be added to CDT's git repo at doc/org.eclipse.cdt.doc.isv/guide/deprecated_API_removals.html and published (starting with CDT 10.0 in Sept 2020) on https://help.eclipse.org/latest/topic/org.eclipse.cdt.doc.isv/guide/deprecated_API_removals.html

Using API Tooling

All committers and contributors should enable API Tooling when writing patches for CDT.

To set up the API baseline, follow these steps:

1. Select "Window -> Preferences". In the window that opens, select "Plug-in Development -> API Baselines" on the left pane.
2. Click on "Add Baseline..."
3. Choose "A target platform" and click Next.
4. In the next page check the box "cdt-baseline".
5. Click "Refresh" to download the contents of the target.
6. Specify a name for this baseline in the top area, like "cdt-baseline" for example.
7. Click "Finish", then "OK" in the next dialog.

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

Note that when a new version of CDT is released, you will need to refresh the baseline

1. Go back to "Window -> Preferences", "Plug-in Development -> API Baselines"
2. Select the cdt baseline and click on Edit...
3. In the next page check the box "cdt-baseline".
4. Click "Refresh" to update the contents of the target.
5. Click "Finish", then "OK" in the next dialog.

(In the future, refreshing manually might not be required, see bug 479055)

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 a bug to yourself
• Set the target milestone field to the 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
• If the patch is > 1,000 lines, it must be submitted for IP review, i.e. CQ in IPZilla. See Development_Resources/Automatic_IP_Log
• Change bug state to fixed. Check again that you set the milestone field.

Committing Code

• API changes have to be discussed in cdt-dev mailing list before committing
• When development reaches cycle where release candidates are built, email to cdt-dev should be sent for every commit you are making
• Non-committers must have a bug associated with every non-cosmetic commit, with bug number at the beginning of commit comment, e.g.:

 Bug 12345 fixed that, added this

• Post a change for review on gerrit
• You may not need gerrit review if changes are cosmetic - formatting, warning fixed, copyright, auto-re factoring, typos in strings.

Version Numbering

See Eclipse Version Numbering Guildlines

Bugs Workflow

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