Difference between revisions of "Papyrus/Papyrus Developer Guide/How To- Code Contributing"

Revision as of 02:41, 3 July 2018

Code Contribution

How to add a Task (Papyrus Bugzilla usage)

When adding a task to the buzilla, the following grammar should be used:

• '[' Category ']' NameOfTheTask
  

The category helps to filter the bugs for developers. There are already some existing categories: General, XXX Diagram, Common, Property View, etc.

As a reminder, the lifecycle of bugs is located here: Bugzilla Use

How to contribute code with Gerrit (non commiter)

If you want to contribute code, and you are not a commiter, here is how to proceed Papyrus Developer Guide/How to Contribute to Papyrus with Gerrit

What to do to contribute a patch

(For further information, see http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf)

When a non-committer wants to contribute to Papyrus, he must create patchs and attach them to a bug. In the comment of each patch, he must write :

• (1) I, Forename Name, wrote 100% of the code I've provided.
• (2) This code contains no cryptography
• (3) I have the right to contribute the code to Eclipse.
• (4) I contribute the content under the EPL.

+ Set the field Review to '?'.

What to check before committing a patch

Before commiting a patch, you should verify that the contributor has written the following lines in the comment :

• (1) I, Forename Name, wrote 100% of the code I've provided.
• (2) This code contains no cryptography
• (3) I have the right to contribute the code to Eclipse.
• (4) I contribute the content under the EPL.

If not, he must do that before you commit its patch!

• If the writer is an employee of the same company and if the compagny has signed a Member Commiter Agreement : after the commit, you should comment the attachment writing :
  • Here is a contribution from one employee of "the name of the company"
  • The company has signed a Member Commiter Agreement.
  • The contribution does not need a CQ.
  • I've committed this contribution.
  • Committed revision xxx.
  • Set the field iplog to +

Note : In reality, you should have the autorization of the PMC before doing this commit.

• If the writer is not an employee of the CEA : you need to do a CQ (http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf. see this guide for more information.

• In all other cases, see http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf

Code formatting

• Before to commit, you should verify these items :
  • your code is formatted using the Papyrus Template
  • each file has an header with the EPL licence and your name
  • all strings are externalized or tagged with //$NON-NLS-1$. see this page for more information.
  • the version numbers are correcct. see this guide for more information.

• Moreover, if you want to commit a patch, please see the point "How to commit a patch".

Commit message

• During the commit :
  • you should comment your commit and precise the id of the bug. see this page for more information about contributing through git and gerrit.

Code Reviews

Here are some guidelines (which may be altered and/or improved) that every reviewer and committer should follow:

• Headers: The headers must include a new entry for each contribution. It will include the bug number, the committer identification (the name is not mandatory, but the company is), updated date brackets (e.g. 2015-2018), respect the format below. This is the EPL 1.0, This will need to be changed when Papyrus will finalize its migration to the new EPL 2.0 licence.

/*****************************************************************************
* Copyright (c) 2015, 2018 CEA LIST, Committer Name, 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:
*   CEA LIST - Initial API and implementation
*   Committer Name (CEA LIST) committer.name@cea.fr - Bug 492522, Bug XXXXXX
*****************************************************************************/

• Javadoc: It should exist for all methods (sometimes a simple @Inherited is enough). Generated javadoc should not be sufficient unless it expresses clearly what the method do, its parameters and return values.
• Strings: Verify the Non-NLS markers.
• Tags: (@since plugin-number, ...)

/**
* Constructs an Editor for multiple Integer values.
* The widget is a List, with controls to move values up/down, add values and remove values.
*
* @param parent
*            The Composite in which this editor is created
* @param directCreation
*            Indicates if the creation and modification are directed.
* @param directCreationWithTreeViewer
*            Indicates if the creation and modification are directed on the TreeViewer.
* @param style
*            The List's style
*
* @since 3.1
*/
public MultipleIntegerEditor(Composite parent, ...){}

• Version numbers: A plugin's version should reflect its changes. Above is a linked to the guidelines and you can use tools to help you such as the integrated Eclipse's API tools.
• Reexports: A contributed code should never introduce any 'hidden' dependencies such as reexporting plugins dependencies.
• Visibility ordering: There is no order of methods or variables in a class (private, public or protected). On the other hand, there is an order when dealing with keywords (private static final Type).
• Attributes: All attributes, field must be at beginning of the class
• Returns and conditions: You can have as many 'return' statement you need in a method.