|
|
(59 intermediate revisions 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}} |
| | | |
− | * It is recommended to use default "Eclipse" code formatting for Java for new code.
| + | [[Category:CDT]] |
− | * 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.
| + | |
− | These errors should be enabled:
| + | |
− | | + | |
− | * 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 [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.'''
| + | |
− | | + | |
− | == Copyright ==
| + | |
− | | + | |
− | Use eclipse copyright header: http://www.eclipse.org/legal/copyrightandlicensenotice.php. Here is an example:
| + | |
− | | + | |
− | <pre>
| + | |
− | /*******************************************************************************
| + | |
− | * 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)
| + | |
− | *******************************************************************************/
| + | |
− | </pre>
| + | |
− | | + | |
− | 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
| + | |
− | | + | |
− | <strong>EXPERIMENTAL</strong>. 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]].
| + | |
− | | + | |
− | == Javadoc ==
| + | |
− | | + | |
− | All public API classes and interfaces must have meaningful javadoc header, as well as all public API members.
| + | |
− | | + | |
− | == Contributing the Patch ==
| + | |
− | | + | |
− | * To fix anything in CDT first you need to create or find existing bugzilla report for this particular problem/enhancement
| + | |
− | * Check out the code from corresponding branch and apply the fix
| + | |
− | * Comment your changes in the code
| + | |
− | * If the changes are significant add your name and company in the contributor list in the file header
| + | |
− | * Follow CDT guidelines for code formating and java warnings/errors
| + | |
− | * To minimize the patch, do not re-format the source code you edited (except changed lines). Do not fix any warnings in the code you are not changing
| + | |
− | * Create a patch "Team->Create Patch" command on changed projects, select Workspace as a scope even when only one file has changed.
| + | |
− | * Submit patch using an attachment to a bug report
| + | |
− | * Mark attachment as a patch
| + | |
− | * If previous patches attached to the bug, which are obsolete now mark them as such
| + | |
− | * Add a comment to which branch the patch should be applied (HEAD by default)
| + | |
− | * Add a comment on what patch is doing, it is not easy to figure it out from the code sometimes
| + | |
− | * Make sure bug report has a clear reproducible scenario, if not add one
| + | |
− | * If you really want to do formatting or styling (such as converting to java 1.5) - create another bug for that and attach a patch
| + | |
− | * To speed up process of applying your patch you should create one or more junit tests as well and attach as separate patch
| + | |
− | * Normally committers are watching new bugzilla activity and somebody would look at your patch in a few days
| + | |
− | * If the patch has not received an attention in a week or so some nagging can help. Send email to mailto:cdt-dev@eclipse.org asking committers to look at the patch
| + | |
− | | + | |
− | see also [[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)
| + | |
− | | + | |
− | == Version Numbering ==
| + | |
− | | + | |
− | See [[Version_Numbering|Eclipse Version Numbering Guildlines]]
| + | |
− | | + | |
− | == Bugs Workflow ==
| + | |
− | For creating and managing bugs see
| + | |
− | http://wiki.eclipse.org/CDT/Bugs
| + | |