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 "Papyrus/Papyrus Developer Guide/How To- Code Contributing"

(Code Rules)
(Code Rules)
 
(34 intermediate revisions by 4 users not shown)
Line 52: Line 52:
 
[[Image:Papyrus.codestandards.plugin.xml.png]]
 
[[Image:Papyrus.codestandards.plugin.xml.png]]
  
 +
=== Papyrus Feature Structure ===
 +
 +
* Papyrus feature id scheme: org.eclipse.papyrus.<feature.name>.feature
 +
**e.g. ''org.eclipse.papyrus.infra.core.feature''
 +
* Papyrus feature Label scheme: Papyrus <Feature Name>
 +
**e.g. ''Papyrus core''
 +
If your feature is still in the incubation state you should add the following to your label: (Incubation)
 +
*Each feature must contain the Eclipse licence reference:
 +
<feature
 +
      id="org.eclipse.papyrus.editor.feature"
 +
      version="2.0.0.qualifier"
 +
      label="%featureName"
 +
      provider-name="%providerName"
 +
      license-feature="org.eclipse.license"
 +
      license-feature-version="2.0.2">
 +
 
 +
  <description url="https://eclipse.org/papyrus/">
 +
    %description
 +
  </description>
 +
 +
  <copyright>
 +
      %copyright
 +
  </copyright>
 +
 +
  <license url="%licenseURL">
 +
      %license
 +
  </license>
 +
  ...
 +
</feature>
 +
 +
*The build.properties file must contain the following files in the "Binary build" section:
 +
**feature.properties which must contains:
 +
*** featureName
 +
*** providerName
 +
*** description
 +
*** copyright
 +
**feature.xml
 +
 +
*The feature must only includes the repository's Papyrus plugins. If you need to make it depends on external plugins or features, be they from another Papyrus repository or any other repository, they should be added through the require of import mechanism. Refrain from using the include method as much as possible.
  
 
=== Code Formatting ===
 
=== Code Formatting ===
Line 61: Line 100:
 
=== Code Rules ===
 
=== Code Rules ===
 
Before committing, you should verify these items&nbsp;:  
 
Before committing, you should verify these items&nbsp;:  
*'''default''' keyword in Interfaces: should be avoided and only used if unavoidable and justified (to prevent unnecessary API break for example)
+
*'''copyright''' each file has an header with the EPL licence and your name  
*'''var''' keyword is forbidden
+
*'''lambda expressions''' are allowed, but must be commented to ease the understanding
+
*each file has an header with the EPL licence and your name  
+
*all strings are externalized or tagged with //$NON-NLS-1$. The goal of the externalization process is to distinguish the string used as messages and visible by the final user and the string required in your code, but not visible for the user. Follow this [https://wiki.eclipse.org/Papyrus/Papyrus_Developer_Guide/Externalize_Strings_In_Java | link] for a guide on externalization in Eclipse.
+
*the version numbers are correct. see [https://wiki.eclipse.org/Version_Numbering this guide] for more information.
+
 
+
Unless there is a good reason as to why, it is the Reviewer that is allowed to merge/push the gerrit patch into the repository. The reviewer must never be the committer of the patch to keep a two way check and minimize errors.<br/>
+
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.
 
* '''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.
 
In addition they must respect the EPL2.0 licensing and, in case of a plugin, include the about.html with the EPL2.0 license summary.
 
In addition they must respect the EPL2.0 licensing and, in case of a plugin, include the about.html with the EPL2.0 license summary.
Line 75: Line 106:
 
  * Copyright (c) 2015, 2018 CEA LIST, Committer Name, and others.
 
  * Copyright (c) 2015, 2018 CEA LIST, Committer Name, and others.
 
  *
 
  *
  * All rights reserved. This program and the accompanying materials
+
  * This program and the accompanying materials
 
  * are made available under the terms of the Eclipse Public License 2.0
 
  * are made available under the terms of the Eclipse Public License 2.0
 
  * which accompanies this distribution, and is available at
 
  * which accompanies this distribution, and is available at
Line 90: Line 121:
 
  # Copyright (c) 2013, 2018 CEA LIST, Committer Name, and others.
 
  # Copyright (c) 2013, 2018 CEA LIST, Committer Name, and others.
 
  #
 
  #
  # All rights reserved. This program and the accompanying materials
+
  # This program and the accompanying materials
 
  # are made available under the terms of the Eclipse Public License 2.0
 
  # are made available under the terms of the Eclipse Public License 2.0
 
  # which accompanies this distribution, and is available at
 
  # which accompanies this distribution, and is available at
Line 101: Line 132:
 
  ###############################################################################
 
  ###############################################################################
  
* '''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.
+
*'''default''' keyword in Interfaces: should be avoided and only used if unavoidable and justified (to prevent unnecessary API break for example)
* '''Strings''': Verify the Non-NLS markers.
+
*'''var''' keyword is forbidden
 +
*'''lambda expressions''' are allowed, but must be commented to ease the understanding
 +
*'''externalized''' strings or tagged with //$NON-NLS-1$. The goal of the externalization process is to distinguish the string used as messages and visible by the final user and the string required in your code, but not visible for the user. Follow this [https://wiki.eclipse.org/Papyrus/Papyrus_Developer_Guide/Externalize_Strings_In_Java link] for a guide on externalization in Eclipse.
 +
* '''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).
 +
* '''Naming''': No abbreviations - the class, methods and variables should have meaningful names.
 +
* '''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.
 +
* '''Javadoc''': It should exist for all methods (sometimes a simple @Inherited is enough). Automatic generation of JavaDoc comments may help, but the automatically generated comments are '''templates'''. They are not sufficient. It is better not to generate javadoc comments than to generate empty comments.  
 +
* '''@SuppressWarnings''' annotations : these annotations are allowed but are not mandatory.
 
* '''Tags''': (@since plugin-number, ...)
 
* '''Tags''': (@since plugin-number, ...)
 
  /**
 
  /**
Line 120: Line 159:
 
  */
 
  */
 
  public MultipleIntegerEditor(Composite parent, ...){}
 
  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.
 
* '''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).
+
* '''Contribution''': A newly written code or plugin should always be added to the relevant poms and features.
* '''Attributes''': All attributes, field must be at beginning of the class
+
*'''versions numbers''' are correct. see [https://wiki.eclipse.org/Version_Numbering this guide] for more information.
* '''Returns and conditions''': You can have as many 'return' statement you need in a method.
+
Unless there is a good reason as to why, it is the Reviewer that is allowed to merge/push the gerrit patch into the repository. The reviewer must never be the committer of the patch to keep a two way check and minimize errors.<br/>
 +
* all generated code shall be contained in the directory '''src-gen'''. Note that all code in this directory is not participant to the API.
  
* '''Features and Manifest''': The variables should be externalized in a properties files when possible. and the features should point to the eclipse license plugin instead of declaring their own.
+
Here are some guidelines (which may be altered and/or improved) that every reviewer and committer should follow:
<feature
+
      id="org.eclipse.papyrus.XXXXXXX.feature"
+
      version="2.0.0.qualifier"
+
      label="%featureName"
+
      provider-name="%providerName"
+
      license-feature="org.eclipse.license"
+
      license-feature-version="2.0.0">
+
+
  <description>
+
      %description
+
  </description>
+
+
  <copyright>
+
      %copyright
+
  </copyright>
+
+
  <license url="%licenseURL">
+
      %license
+
  </license>
+
  
=== Write Documentation for Papyrus ===
+
====Generated Code====
Each new contribution must contribute to the documentation (behavior changes or new feature).  
+
'''EMF''', '''GMF''' and '''Xtend''' are used to generate java code.
The documentation must be splitted in two parts:
+
*'''EMF''' and '''GMF'''
*user documentation
+
** when we use these frameworks, the generation must be done in a dedicated folder, generally named '''src-gen'''.
*developer documentation
+
** this '''src-gen''' must only contains the generated code
 +
** this generated code must not be modified by the developper, several ways are available to avoid to have to write ''@Generated NOT'' in the generated code.
 +
** if for a well identified usecase you need to modify the generated code, after a validation of the Papyrus Team, you must write a dedicated JUnit tests to check that your custom code is never erased by a future re-generation.
 +
** currently this generated code is committed on the git, but maybe in the future it will be generated by the build process.
 +
** concerning the modifications done in an *.ecore or *.gmfgen file, we recommand to update the year in the generated header in the *.ecore/*.gmfgen file and that's all. For example, just edit the line '''Copyright (c) 2014 CEA LIST and others.''' becomes '''Copyright (c) 2014, 2021 CEA LIST and others.''' Of course, you can also add your company into this line.
  
How to - Related to documentation [[Papyrus Developer Guide/Writing Documentation]]
+
*'''Xtend'''
 +
** when we use these frameworks, the generation must be done in a dedicated folder generally, named '''xtend-gen'''.
 +
** as for '''EMF''', you must not modify the generated code.
 +
** the code is generated by the build process, so the generated java code must not be committed on the git.
 +
 
 +
===Logger===
 +
You must '''not''' use the standard console output in Papyrus plug-ins. Use the [https://wiki.eclipse.org/Papyrus/Papyrus_Developer_Guide/Papyrus_Log Papyrus log] instead.
  
 
=== Plugin Versioning - Deprecated code ===
 
=== Plugin Versioning - Deprecated code ===
Line 169: Line 198:
 
  <nowiki>
 
  <nowiki>
 
/**
 
/**
*
 
 
  * @deprecated since 3.1
 
  * @deprecated since 3.1
 
  *            use {@link org.eclipse.papyrus.infra.gmfdiag.common.structure.DiagramStructure} API instead
 
  *            use {@link org.eclipse.papyrus.infra.gmfdiag.common.structure.DiagramStructure} API instead
 
  *
 
  *
 
  *            This class will be removed in Papyrus 5.0, see Bug 541027
 
  *            This class will be removed in Papyrus 5.0, see Bug 541027
*
 
*
 
 
  */
 
  */
 
@Deprecated
 
@Deprecated
Line 182: Line 208:
 
}
 
}
 
</nowiki>
 
</nowiki>
 +
 +
=== Automatic check ===
 +
 +
Most of these rules are checked automatically when running the Papyrus tests. If you want to check them locally, use the plug-in ''org.eclipse.papyrus.bundles.tests'' (''Run as &gt; Junit plug-in test'' or use the ''*.launch'' file from this plug-in). This plug-in can be retrieved on the Papyrus Git repository: [https://git.eclipse.org/c/papyrus/org.eclipse.papyrus.git/tree/tests/junit/framework/org.eclipse.papyrus.bundles.tests org.eclipse.papyrus.bundles.tests].
  
 
=== API ===
 
=== API ===
Line 191: Line 221:
 
  * qualified name of the class
 
  * qualified name of the class
  
* See the folowing example
+
* See the following example
  
 
  ### The profile validation must be done with a button 'Validate Profile plug-in' on plug-in, in the papyrus developer menu
 
  ### The profile validation must be done with a button 'Validate Profile plug-in' on plug-in, in the papyrus developer menu
Line 203: Line 233:
 
  ### A checker for the definition profile must be implemented
 
  ### A checker for the definition profile must be implemented
 
  * org.eclipse.papyrus.toolsmiths.validation.profile.internal.checkers.ProfileDefinitionChecker
 
  * org.eclipse.papyrus.toolsmiths.validation.profile.internal.checkers.ProfileDefinitionChecker
 +
 +
== Write Documentation for Papyrus ==
 +
Each new contribution must contribute to the documentation (behavior changes or new feature).
 +
The documentation must be splitted in two parts:
 +
*user documentation
 +
*developer documentation
 +
 +
How to - Related to documentation [[Papyrus Developer Guide/Writing Documentation]]
  
 
== Contribute ==
 
== Contribute ==
Line 208: Line 246:
 
===ECA===
 
===ECA===
 
The developer should have signed the [https://www.eclipse.org/legal/ECA.php Eclipse Contributor Agreement]
 
The developer should have signed the [https://www.eclipse.org/legal/ECA.php Eclipse Contributor Agreement]
If the writer is an employee of the same company and if the compagny has signed a Member Commiter Agreement&nbsp;: after the commit, you should comment the attachment writing&nbsp;:  
+
If the writer is an employee and his company has signed a Member Committer Agreement&nbsp;: after the commit, you should comment the attachment writing&nbsp;:  
 
*Here is a contribution from one employee of "the name of the company"  
 
*Here is a contribution from one employee of "the name of the company"  
*The company has signed a Member Commiter Agreement.  
+
*The company has signed a Member Committer Agreement.  
 
*The contribution does not need a CQ.  
 
*The contribution does not need a CQ.  
 
*I've committed this contribution.  
 
*I've committed this contribution.  
Line 216: Line 254:
 
*Set the field iplog to +
 
*Set the field iplog to +
  
Note&nbsp;: In reality, you should have the autorization of the PMC before doing this commit.  
+
Note&nbsp;: In reality, you should have the authorization of the PMC before doing this commit.
 
+
If the writer is not an employee of the CEA&nbsp;: you need to do a CQ (http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf. see [https://wiki.eclipse.org/Papyrus/Papyrus_Developer_Guide/Contribution_Questionaire this guide] for more information.
+
 
+
In all other cases, see http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf
+
  
 
=== CQs ===
 
=== CQs ===
 
Remember to check on the current CQs to see if they are still current and that we will not miss any currently required dependencies (e.g. glazed lists in the new orbit or the new apache.common.io dependency) as well as the IPlogs. A quick tutorial on CQs can be found [https://wiki.eclipse.org/Papyrus_Developer_Guide/Contribution_Questionaire here].
 
Remember to check on the current CQs to see if they are still current and that we will not miss any currently required dependencies (e.g. glazed lists in the new orbit or the new apache.common.io dependency) as well as the IPlogs. A quick tutorial on CQs can be found [https://wiki.eclipse.org/Papyrus_Developer_Guide/Contribution_Questionaire here].
 +
 +
If you have any doubt about your contribution you can always check this [https://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf Eclipse chart] for more information.
  
 
=== Gerrit ===
 
=== Gerrit ===
  
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]]
+
If you want to contribute code, and you are not a committer, here is how to proceed:
  
(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 using the Bug number in the message (e.g. commit -m "Bug 561154 - xyz"), this will automatically contribute the patch to the Bugzilla ticket. In the comment of each patch, he must write&nbsp;:  
 
+
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&nbsp;:  
+
  
 
* I, Forename Name, wrote 100% of the code I've provided.  
 
* I, Forename Name, wrote 100% of the code I've provided.  
 
* This code contains no cryptography  
 
* This code contains no cryptography  
 
* I have the right to contribute the code to Eclipse.  
 
* I have the right to contribute the code to Eclipse.  
* I contribute the content under the EPL.
+
* I contribute the content under the EPL 2.0.
  
+ Set the field Review to '?'.
+
see [https://wiki.eclipse.org/Papyrus/Papyrus_Developer_Guide/How_to_Contribute_to_Papyrus_with_Gerrit this page] for more information about contributing through Git and Gerrit.
  
=== Commit message ===
+
Please, note that contributions with Merge commits will be rejected. We prefer rebased contributions to get a linear history.
*During the commit&nbsp;:
+
**you should comment your commit and precise the id of the bug. see [https://wiki.eclipse.org/Papyrus/Papyrus_Developer_Guide/How_to_Contribute_to_Papyrus_with_Gerrit this page] for more information about contributing through git and gerrit.
+
  
 
== Code Reviews ==
 
== Code Reviews ==
 
The reviewer shall verify that the contribution respects all  [https://wiki.eclipse.org/Papyrus/Papyrus_Developer_Guide/How_To-_Code_Contributing#Code_Rules aforementioned rules].
 
The reviewer shall verify that the contribution respects all  [https://wiki.eclipse.org/Papyrus/Papyrus_Developer_Guide/How_To-_Code_Contributing#Code_Rules aforementioned rules].
 +
 +
Therefore, If there are unmerged, and chained, contributions on gerrit, any correction based on comments should be contributed as an amend of the existing patch and the next, chained, contributions rebased on top of it (and not in a future contribution).
  
 
== Merge ==
 
== Merge ==
Line 258: Line 292:
 
*RC1+
 
*RC1+
 
  Its forbidden to merge contribution. Only by the project Chief for critical bugs.
 
  Its forbidden to merge contribution. Only by the project Chief for critical bugs.
 +
 +
[[Category:Papyrus]]

Latest revision as of 08:26, 9 May 2023


All papyrus contributors shall follow these rules:

Write a Bugzilla task

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

  • Your contribution shall be associated to a bug refenced in the bugzilla.
  • When a bug is opened/resolved/closed the Target Milestone must be filled. For example the bug has been fixed for the service release 3 of oxygen, the target milestone is 3.3.


Write the code

Papyrus Plugin Structure

  • All plug-ins must compile and run against JavaSE-1.8. Papyrus 5.0 must compile against openjdk-11.
  • Plug-in provider : Eclipse Modeling Project
  • Version :
  • Plug-in name : must end with (Incubation) if version is less than 1.0.0 . If the version is at least 1.0.0, the (Incubation) suffix must be removed.
  • Plug-in ID : must start with org.eclipse.papyrus.
  • Plug-in dependencies must not be re-exported.
  • plug-in dependencies must be defined with min and max version values, e.g. depends on oep.infra.core;bundle-version="[1.2.0,2.0.0)" instead of oep.infra.core or oep.infra.core;bundle-version="1.2.0")
    • The Papyrus Developer Tools has an action Update Dependency Ranges in the Plug-in Tools context menu of plug-in projects and manifest files that automatically assigns bundle dependency ranges compatible with the current PDE target and workspace
  • The build.properties file describes the files that must be included at runtime. It is important to fill it properly, so that plug-ins can work correctly once installed. Especially, you should probably always include the following files and folders (When they exist), in the "Binary build" (field bin.includes in build.properties) category:
    • META-INF/
    • about.html
    • icons/, images/, resources/, models/, etc. (All folders containing runtime resources)
    • plugin.properties
    • plugin.xml
    • schema/
  • Do not include the following files:
    • .classpath
    • .project
    • bin/, src/, src-gen/, custom-src/
    • build.properties
  • The Source build (field src.includes in build.properties) category must contain the about.html file:
  • It must not contain the following:
    • src/, src-gen/, custom-src/
    • All files and directories are already contained in the "Binary build" category (Except the about.html which must be contained in both Binary and Source builds)

plugin.xml:
Papyrus.codestandards.plugin.xml.png

Papyrus Feature Structure

  • Papyrus feature id scheme: org.eclipse.papyrus.<feature.name>.feature
    • e.g. org.eclipse.papyrus.infra.core.feature
  • Papyrus feature Label scheme: Papyrus <Feature Name>
    • e.g. Papyrus core

If your feature is still in the incubation state you should add the following to your label: (Incubation)

  • Each feature must contain the Eclipse licence reference:
<feature
     id="org.eclipse.papyrus.editor.feature"
     version="2.0.0.qualifier"
     label="%featureName"
     provider-name="%providerName" 
     license-feature="org.eclipse.license"
     license-feature-version="2.0.2">
  
  <description url="https://eclipse.org/papyrus/">
  	  %description
  </description>

  <copyright>
     %copyright
  </copyright>

  <license url="%licenseURL">
     %license
  </license> 
  ...
</feature>
  • The build.properties file must contain the following files in the "Binary build" section:
    • feature.properties which must contains:
      • featureName
      • providerName
      • description
      • copyright
    • feature.xml
  • The feature must only includes the repository's Papyrus plugins. If you need to make it depends on external plugins or features, be they from another Papyrus repository or any other repository, they should be added through the require of import mechanism. Refrain from using the include method as much as possible.

Code Formatting

Before writing any code you should check that you have the papyrus templates set as your format in your IDE. These can be retrieved following these steps.

These could also be retreived and applied from the .settings folder of each plugins. (An example can be found here)

Code Rules

Before committing, you should verify these items :

  • copyright each file has an header with the EPL licence and your name
  • 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.

In addition they must respect the EPL2.0 licensing and, in case of a plugin, include the about.html with the EPL2.0 license summary.

/*****************************************************************************
* Copyright (c) 2015, 2018 CEA LIST, Committer Name, and others.
*
* This program and the accompanying materials
* are made available under the terms of the Eclipse Public License 2.0
* which accompanies this distribution, and is available at
* https://www.eclipse.org/legal/epl-2.0/
*
* SPDX-License-Identifier: EPL-2.0
*
* Contributors:
* CEA LIST - Initial API and implementation
* Committer Name (CEA LIST) committer.name@cea.fr - Bug 492522, Bug XXXXXX
*****************************************************************************/
###############################################################################
# Copyright (c) 2013, 2018 CEA LIST, Committer Name, and others.
#
# This program and the accompanying materials
# are made available under the terms of the Eclipse Public License 2.0
# which accompanies this distribution, and is available at
# https://www.eclipse.org/legal/epl-2.0/
#
# SPDX-License-Identifier: EPL-2.0
#
# Contributors:
#
###############################################################################
  • default keyword in Interfaces: should be avoided and only used if unavoidable and justified (to prevent unnecessary API break for example)
  • var keyword is forbidden
  • lambda expressions are allowed, but must be commented to ease the understanding
  • externalized strings or tagged with //$NON-NLS-1$. The goal of the externalization process is to distinguish the string used as messages and visible by the final user and the string required in your code, but not visible for the user. Follow this link for a guide on externalization in Eclipse.
  • 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).
  • Naming: No abbreviations - the class, methods and variables should have meaningful names.
  • 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.
  • Javadoc: It should exist for all methods (sometimes a simple @Inherited is enough). Automatic generation of JavaDoc comments may help, but the automatically generated comments are templates. They are not sufficient. It is better not to generate javadoc comments than to generate empty comments.
  • @SuppressWarnings annotations : these annotations are allowed but are not mandatory.
  • 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, ...){}
  • Reexports: A contributed code should never introduce any 'hidden' dependencies such as reexporting plugins dependencies.
  • Contribution: A newly written code or plugin should always be added to the relevant poms and features.
  • versions numbers are correct. see this guide for more information.

Unless there is a good reason as to why, it is the Reviewer that is allowed to merge/push the gerrit patch into the repository. The reviewer must never be the committer of the patch to keep a two way check and minimize errors.

  • all generated code shall be contained in the directory src-gen. Note that all code in this directory is not participant to the API.

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

Generated Code

EMF, GMF and Xtend are used to generate java code.

  • EMF and GMF
    • when we use these frameworks, the generation must be done in a dedicated folder, generally named src-gen.
    • this src-gen must only contains the generated code
    • this generated code must not be modified by the developper, several ways are available to avoid to have to write @Generated NOT in the generated code.
    • if for a well identified usecase you need to modify the generated code, after a validation of the Papyrus Team, you must write a dedicated JUnit tests to check that your custom code is never erased by a future re-generation.
    • currently this generated code is committed on the git, but maybe in the future it will be generated by the build process.
    • concerning the modifications done in an *.ecore or *.gmfgen file, we recommand to update the year in the generated header in the *.ecore/*.gmfgen file and that's all. For example, just edit the line Copyright (c) 2014 CEA LIST and others. becomes Copyright (c) 2014, 2021 CEA LIST and others. Of course, you can also add your company into this line.
  • Xtend
    • when we use these frameworks, the generation must be done in a dedicated folder generally, named xtend-gen.
    • as for EMF, you must not modify the generated code.
    • the code is generated by the build process, so the generated java code must not be committed on the git.

Logger

You must not use the standard console output in Papyrus plug-ins. Use the Papyrus log instead.

Plugin Versioning - Deprecated code

Using the @Deprecated tag, you must do these things in the same time:

  • increase the minor version of the plugin (of course, only if it has not yet be done since the last release)
    • NB : if you just add @Deprecated tag in a plugin, it is normally not required to increase the plugin version. Nevertheless, we decided to increase the minor of a such plugin, in order to be able to know easily when the object became deprecated. Depending of the API Tools configuration, you can get an error doing this. In this case configure your API tools to ignore it.
  • indicate in the comment the plugin version when the class/method became deprecated
  • open a bug to remove the deprecated class/method in the next major release
  • reference this bug in the comment of the deprecated class/method
  • (optional) indicate in the comment in which major release the class/method will be remove

Add the end, you must have something like that:

/**
 * @deprecated since 3.1
 *             use {@link org.eclipse.papyrus.infra.gmfdiag.common.structure.DiagramStructure} API instead
 *
 *             This class will be removed in Papyrus 5.0, see Bug 541027
 */
@Deprecated
public abstract class DiagramStructure {
...
}

Automatic check

Most of these rules are checked automatically when running the Papyrus tests. If you want to check them locally, use the plug-in org.eclipse.papyrus.bundles.tests (Run as > Junit plug-in test or use the *.launch file from this plug-in). This plug-in can be retrieved on the Papyrus Git repository: org.eclipse.papyrus.bundles.tests.

API

  • Code of plugins shall be inside internal package
  • API shall be public and each classe presence shall be justified by implementation of usecase
  • The usecase are store inside the plugin the name of the file XXX.usecases.md
  • The grammar is:
### requirement text 
* qualified name of the class
  • See the following example
### The profile validation must be done with a button 'Validate Profile plug-in' on plug-in, in the papyrus developer menu
* org.eclipse.papyrus.toolsmiths.validation.profile.handlers.ValidateProfilePluginHandler
* org.eclipse.papyrus.toolsmiths.validation.profile.testers.ValidateProfilePluginTester
* plugin.xml
###  During the validation, a progress monitor must be opened with correct explanations
* org.eclipse.papyrus.toolsmiths.validation.profile.handlers.ValidateProfilePluginHandler
### A checker for the extensions must be implemented
* org.eclipse.papyrus.toolsmiths.validation.profile.internal.checkers.ProfileExtensionsChecker
### A checker for the definition profile must be implemented
* org.eclipse.papyrus.toolsmiths.validation.profile.internal.checkers.ProfileDefinitionChecker

Write Documentation for Papyrus

Each new contribution must contribute to the documentation (behavior changes or new feature). The documentation must be splitted in two parts:

  • user documentation
  • developer documentation

How to - Related to documentation Papyrus Developer Guide/Writing Documentation

Contribute

ECA

The developer should have signed the Eclipse Contributor Agreement If the writer is an employee and his company has signed a Member Committer 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 Committer 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 authorization of the PMC before doing this commit.

CQs

Remember to check on the current CQs to see if they are still current and that we will not miss any currently required dependencies (e.g. glazed lists in the new orbit or the new apache.common.io dependency) as well as the IPlogs. A quick tutorial on CQs can be found here.

If you have any doubt about your contribution you can always check this Eclipse chart for more information.

Gerrit

If you want to contribute code, and you are not a committer, here is how to proceed:

When a non-committer wants to contribute to Papyrus, he must create patchs and attach them to a bug using the Bug number in the message (e.g. commit -m "Bug 561154 - xyz"), this will automatically contribute the patch to the Bugzilla ticket. In the comment of each patch, he must write :

  • I, Forename Name, wrote 100% of the code I've provided.
  • This code contains no cryptography
  • I have the right to contribute the code to Eclipse.
  • I contribute the content under the EPL 2.0.

see this page for more information about contributing through Git and Gerrit.

Please, note that contributions with Merge commits will be rejected. We prefer rebased contributions to get a linear history.

Code Reviews

The reviewer shall verify that the contribution respects all aforementioned rules.

Therefore, If there are unmerged, and chained, contributions on gerrit, any correction based on comments should be contributed as an amend of the existing patch and the next, chained, contributions rebased on top of it (and not in a future contribution).

Merge

Eclipse release calendar is detailled here. Each date of releases (M1, M2, M3, RC1, RC2 and GA) for the new Eclipse version is defined in a associated wiki page of the Eclipse version).

Contributions should be merged before:

  • M2+
It is forbidden to modify the GUI. Only important bug fixes should be merged. 
Creation of a branch (tag) for the release
  • M3+
It is forbidden to modify the features and general architecture.
  • RC1+
Its forbidden to merge contribution. Only by the project Chief for critical bugs.

Back to the top