Skip to main content
Jump to: navigation, search

Difference between revisions of "Papyrus/Code Standards"

m (Features: change item order to match alphabetical order (and what we see on screen))
 
(20 intermediate revisions by 8 users not shown)
Line 3: Line 3:
 
These rules apply to all plug-ins and features developed for the Papyrus Eclipse project, and distributed under the EPL licence.  
 
These rules apply to all plug-ins and features developed for the Papyrus Eclipse project, and distributed under the EPL licence.  
  
== Plug-ins ==
 
  
*All plug-ins must compile and run with Java 1.5 (''Execution Environment = J2SE-1.5'')
+
==Features and Plugins==
*Plug-in provider : ''Eclipse Modeling Project''
+
We prefer when the Bundle-Name and Bundle-Vendor fields are externalized in the properties file.
*Version :
+
So we expect a file bundle.properties (or sometimes renamed into plugin.properties) for Plug-In, and a file feature.properties for Feature.
**Juno : ''0.9.2.qualifier''
+
A such file must be embedded in the binary build, so you must check in the ''Build Configuration'' tab that the file is selected.
**Kepler : ''0.10.0.qualifier''
+
*Plug-in name : must end with (Incubation). e.g. ''Papyrus Backbone (Incubation)''
+
*Plug-in ID : must start with org.eclipse.papyrus
+
*Plug-in dependencies must not be re-exported
+
*Dependencies to Papyrus plug-ins must match the current version (e.g. depend on ''oep.infra.core 0.9.2'' instead of ''oep.infra.core'')
+
*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" 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'' category '''must''' contain the following file:
+
**about.html
+
*Optionnally, it may contain the following files:
+
**.classpath
+
**build.properties
+
*It '''must not''' contain the following:
+
**src/, src-gen/, custom-src/
+
**All files and directories which are already contained in the "Binary build" category (Except about.html which must be contained in both Binary and Source builds)
+
 
+
== Java classes ==
+
 
+
*All APIs must be documented with JavaDoc comments. Automatic generation of JavaDoc comments may help, but the automatically generated comments are '''templats'''. They are not sufficient. It is better not to generate javadoc comments than to generate empty comments.
+
*Each Java class must contain the Copyright/Licence/Contributor header. e.g.:
+
 
+
<source lang="java">/*****************************************************************************
+
* Copyright (c) 2013 CEA LIST.
+
*
+
* 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:
+
*  Camille Letavernier (CEA LIST) camille.letavernier@cea.fr - Initial API and implementation
+
*****************************************************************************/</source>
+
 
+
*You must '''not''' use the standard console output in Papyrus plug-ins. Use the [[Papyrus Developer Guide/Papyrus Log|Papyrus log]] instead
+
  
 
== Features  ==
 
== Features  ==
Line 59: Line 14:
 
**Main Papyrus components: org.eclipse.papyrus.&lt;feature.name&gt;.feature  
 
**Main Papyrus components: org.eclipse.papyrus.&lt;feature.name&gt;.feature  
 
***e.g. ''org.eclipse.papyrus.infra.core.feature''  
 
***e.g. ''org.eclipse.papyrus.infra.core.feature''  
**Extra components: org.eclipse.papyrus.extra.&lt;feature.name&gt;.feature
+
*Name: Papyrus &lt;Feature Name&gt;
***e.g. ''org.eclipse.papyrus.extra.marte.feature''  
+
**e.g. ''Papyrus Core''  
*Name: Papyrus &lt;Feature Name&gt; (Incubation)
+
**e.g. ''Papyrus Model2Doc (Incubation)''
**e.g. ''Papyrus core (Incubation)''  
+
***Incubation plugin and feature have a version lower than 1.0.0
**e.g. ''Papyrus Marte (Incubation)''  
+
***Here you will find a definition of incubation: [[Development_Resources/Process_Guidelines/What_is_Incubation]]
*Each feature must contain the files ''epl-v10.html'' and ''license.html'' (February 1 2011)
+
*Each feature.xml file must contains:
 +
**in ''Information Tab -> Copyright Notice'',
 +
*** ''Optional URL'' : ''https://www.eclipse.org/legal/epl-2.0/''
 +
*** ''Copyright'' :
 +
<blockquote>
 +
Copyright (c) 20XX CEA LIST
 +
<br/>
 +
All rights reserved. This program and the accompanying materials
 +
are made available under the terms of the Eclipse Public License
 +
2.0
 +
<br/>
 +
which accompanies this distribution, and is available at
 +
https://www.eclipse.org/legal/epl-2.0/
 +
<br/>
 +
SPDX-License-Identifier: EPL-2.0
 +
</blockquote>
 +
 
 +
[[Image:CopyrightNoticeFeature.png|700px|thumb|none]]
 +
 
 +
** in ''Information Tab -> License Agreement''
 +
***Check the field ''Shared License'',
 +
***License Feature ID: ''org.eclipse.license'',
 +
***License Feature Version: ''2.0.2''.
 +
 
 +
[[Image:LicenseAgreementFeature.png|700px|thumb|none]]
 +
 
 
*The build.properties file must contain the following files in the "Binary build" section:  
 
*The build.properties file must contain the following files in the "Binary build" section:  
**epl-v10.html
 
**feature.xml
 
 
**feature.properties (When available)  
 
**feature.properties (When available)  
**licence.html
+
**feature.xml
*The build.properties file must contain the following files in the "Source build" section:
+
**build.properties (Optional)
+
**epl-v10.html
+
**licence.html
+
  
 
<br>
 
<br>
  
= Tests =
+
[[Image:Papyrus.Build.properties-selectedOptions.png|1000px|thumb|none]]
  
== Test plug-ins ==
+
<br>
 
+
Each plug-in contributed within the Papyrus project must be accompanied with a Test plug-in (And their associated Feature). Each test plug-in must ''at least'' contain a test class so that it can be included to the build/test infrastructure. Of course, the more tests it actually contains, the better...
+
  
The test plug-ins and features must follow the same rules as the other Papyrus plug-ins.  
+
==Additional information for the build process==
 +
The build process also needs to know where is the license. There are 2 solutions :
 +
===Option 1===
 +
In the main pom.xml file (often in the pom.xml of ''releng/folder''), you must write:
  
== Automatic check ==
+
<repositories>
 +
<repository>
 +
<id>license-feature</id>
 +
<url>http://download.eclipse.org/cbi/updates/license/</url>
 +
<layout>p2</layout>
 +
</repository>
 +
</repositories>
  
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 SVN repository: http://dev.eclipse.org/svnroot/modeling/org.eclipse.mdt.papyrus/trunk/tests/junit/plugins/developer/org.eclipse.papyrus.bundles.tests
+
===Option 2===
 +
Your target platform definition file (tpd) must also contains:  
 +
location "http://download.eclipse.org/cbi/updates/license/" eclipse-license {
 +
  org.eclipse.license.feature.group lazy
 +
}
  
 
[[Category:Papyrus]]
 
[[Category:Papyrus]]

Latest revision as of 10:37, 19 November 2020

Coding rules for Papyrus plug-ins and features

These rules apply to all plug-ins and features developed for the Papyrus Eclipse project, and distributed under the EPL licence.


Features and Plugins

We prefer when the Bundle-Name and Bundle-Vendor fields are externalized in the properties file. So we expect a file bundle.properties (or sometimes renamed into plugin.properties) for Plug-In, and a file feature.properties for Feature. A such file must be embedded in the binary build, so you must check in the Build Configuration tab that the file is selected.

Features

  • ID:
    • Main Papyrus components: org.eclipse.papyrus.<feature.name>.feature
      • e.g. org.eclipse.papyrus.infra.core.feature
  • Name: Papyrus <Feature Name>
  • Each feature.xml file must contains:

Copyright (c) 20XX CEA LIST
All rights reserved. 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

CopyrightNoticeFeature.png
    • in Information Tab -> License Agreement
      • Check the field Shared License,
      • License Feature ID: org.eclipse.license,
      • License Feature Version: 2.0.2.
LicenseAgreementFeature.png
  • The build.properties file must contain the following files in the "Binary build" section:
    • feature.properties (When available)
    • feature.xml


Papyrus.Build.properties-selectedOptions.png


Additional information for the build process

The build process also needs to know where is the license. There are 2 solutions :

Option 1

In the main pom.xml file (often in the pom.xml of releng/folder), you must write:

<repositories>
		<repository>
			<id>license-feature</id>
			<url>http://download.eclipse.org/cbi/updates/license/</url>
			<layout>p2</layout>
		</repository>
</repositories>

Option 2

Your target platform definition file (tpd) must also contains:

location "http://download.eclipse.org/cbi/updates/license/" eclipse-license {
 org.eclipse.license.feature.group lazy
}

Back to the top