|
|
| (One intermediate revision by the same user not shown) |
| Line 1: |
Line 1: |
| − | == Code Formatting ==
| + | {{warning|Note: The contents of this page has been migrated to GitHub. Please see the [https://github.com/eclipse-cdt/cdt/blob/main/POLICY.md Policy Guide] for current information or page history for historical information}} |
| − | | + | |
| − | These are the coding style recommendations that are in place with project setting. They are enforced by the [https://github.com/eclipse-cdt/cdt-infra/tree/master/jenkins/pipelines/cdt/verify#cdt-verify-code-cleanliness 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 [https://github.com/eclipse-cdt/cdt-infra/tree/master/jenkins/pipelines/cdt/verify#cdt-verify-code-cleanliness build process].
| + | |
| − | | + | |
| − | All committers and contributors submitting patches should enable [http://wiki.eclipse.org/PDE/API_Tools/User_Guide#API_Tooling_Setup 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 [https://git.eclipse.org/c/cdt/org.eclipse.cdt.git/tree/releng/scripts/check_code_cleanliness.sh 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:
| + | |
| − | | + | |
| − | <pre>
| + | |
| − | /********************************************************************************
| + | |
| − | * 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
| + | |
| − | ********************************************************************************/
| + | |
| − | </pre>
| + | |
| − | | + | |
| − | 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. | + | |
| − | | + | |
| − | === New default methods in interfaces ===
| + | |
| − | | + | |
| − | According to [[Eclipse/API_Central|Eclipse API Central]] and the PDE API tooling, adding a new method to an interface breaks compatibility. However CDT allows an exception. A new default method is allowed in an interface if there is good reason to believe that the new method name will not conflict with any existing implementations. The reason for this exception is to avoid the common and more complicated use case of adding new subinterfaces with *2 naming scheme. An API filter will be needed in this case to prevent the API tooling error that would require a major version bump. Please send an email to cdt-dev to consult with the community if you are unsure.
| + | |
| − | | + | |
| − | === Deprecating and Deleting API ===
| + | |
| − | | + | |
| − | The Eclipse CDT project follows the same guidelines and policies as the Eclipse Platform project. See [[Eclipse/API_Central/Deprecation_Policy|Deprecation Policy]]. The changes to the policy are:
| + | |
| − | | + | |
| − | # Removal of any Eclipse CDT API requires approval from the Eclipse CDT Committers.
| + | |
| − | # 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.
| + | |
| − | # API Changes should be listed in the [[CDT/User/NewInCDT|New and Noteworthy]] wiki page.
| + | |
| − | # API removals and API breakages, actual or planned, should be added to CDT's git repo at [https://git.eclipse.org/c/cdt/org.eclipse.cdt.git/tree/doc/org.eclipse.cdt.doc.isv/guide/deprecated_API_removals.html 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. The current master version can be previewed [https://htmlpreview.github.io/?https://raw.githubusercontent.com/eclipse-cdt/cdt/blob/master/doc/org.eclipse.cdt.doc.isv/guide/deprecated_API_removals.html here].
| + | |
| − | | + | |
| − | === Using API Tooling ===
| + | |
| − | | + | |
| − | All committers and contributors should enable API Tooling when writing patches for CDT.<br>
| + | |
| − | | + | |
| − | To set up the API baseline, follow these steps:
| + | |
| − | | + | |
| − | # Select "Window -> Preferences". In the window that opens, select "Plug-in Development -> API Baselines" on the left pane.
| + | |
| − | # Click on "Add Baseline..."
| + | |
| − | # Choose "A target platform" and click Next.
| + | |
| − | # In the next page check the box "cdt-baseline".
| + | |
| − | # Click "Refresh" to download the contents of the target.
| + | |
| − | # Specify a name for this baseline in the top area, like "cdt-baseline" for example.
| + | |
| − | # 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'''
| + | |
| − | # Go back to "Window -> Preferences", "Plug-in Development -> API Baselines"
| + | |
| − | # Select the cdt baseline and click on Edit...
| + | |
| − | # In the next page check the box "cdt-baseline".
| + | |
| − | # Click "Refresh" to update the contents of the target.
| + | |
| − | # Click "Finish", then "OK" in the next dialog.
| + | |
| − | | + | |
| − | (In the future, refreshing manually might not be required, see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=479055 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 [[Version_Numbering|Eclipse Version Numbering Guildlines]]
| + | |
| − | | + | |
| − | == Bugs Workflow ==
| + | |
| − | For creating and managing bugs see
| + | |
| − | http://wiki.eclipse.org/CDT/Bugs
| + | |
| | | | |
| | [[Category:CDT]] | | [[Category:CDT]] |
