Skip to main content
Jump to: navigation, search

Difference between revisions of "OAW Developer Guidelines"

Line 19: Line 19:
 
* In order to ensure we only use Java 5, all projects get a project specific compiler setting. --[[User:Peter.friese.itemis.de|Peter.friese.itemis.de]] 10:03, 30 April 2008 (EDT)
 
* In order to ensure we only use Java 5, all projects get a project specific compiler setting. --[[User:Peter.friese.itemis.de|Peter.friese.itemis.de]] 10:03, 30 April 2008 (EDT)
 
* Target platform is Eclipse 3.3 (4?) --[[User:Jan.koehnlein.itemis.de|Jan.koehnlein.itemis.de]] 08:51, 30 April 2008 (EDT)
 
* Target platform is Eclipse 3.3 (4?) --[[User:Jan.koehnlein.itemis.de|Jan.koehnlein.itemis.de]] 08:51, 30 April 2008 (EDT)
 +
* Target standalone environment is Equinox, however it should be possible to run outside of OSGi as well [[User:B.kolb.kolbware.de|B.kolb.kolbware.de]] 10:30, 2 Mai 2008 (EDT)
  
 
== Coding ==
 
== Coding ==
Line 31: Line 32:
 
   id="org.openarchitectureware.core.properties.MetamodelContributorsPropertyPage"
 
   id="org.openarchitectureware.core.properties.MetamodelContributorsPropertyPage"
 
</source>
 
</source>
 +
* All code has to be written with an OSGi environment in mind (classloading, reflection) [[User:B.kolb.kolbware.de|B.kolb.kolbware.de]] 10:30, 2 Mai 2008 (EDT)
  
  
Line 52: Line 54:
 
* If you add a plug-in, add it to at least one feature. --[[User:Jan.koehnlein.itemis.de|Jan.koehnlein.itemis.de]] 08:51, 30 April 2008 (EDT)
 
* If you add a plug-in, add it to at least one feature. --[[User:Jan.koehnlein.itemis.de|Jan.koehnlein.itemis.de]] 08:51, 30 April 2008 (EDT)
 
* The name of a feature should always end with ''.feature''. --[[User:Jan.koehnlein.itemis.de|Jan.koehnlein.itemis.de]] 08:57, 30 April 2008 (EDT)
 
* The name of a feature should always end with ''.feature''. --[[User:Jan.koehnlein.itemis.de|Jan.koehnlein.itemis.de]] 08:57, 30 April 2008 (EDT)
 +
* The ID of a feature has to be equivalent with the 'main' plugin in the feature. So the feature name is the main plugin name + ''.feature''
 
* We need a way to communicate the addition of stuff to the project sets so everybody gets automatically notified and can check out the additional plug-ins. Suggestion: have Nick write a tool that scans .psf files for changes and notifies all developers of the respective module about this addition. --[[User:Peter.friese.itemis.de|Peter.friese.itemis.de]] 09:52, 30 April 2008 (EDT)
 
* We need a way to communicate the addition of stuff to the project sets so everybody gets automatically notified and can check out the additional plug-ins. Suggestion: have Nick write a tool that scans .psf files for changes and notifies all developers of the respective module about this addition. --[[User:Peter.friese.itemis.de|Peter.friese.itemis.de]] 09:52, 30 April 2008 (EDT)
 
* We do NOT use Require-Bundle to import OSGi bundles, but instead use Import-Package. --[[User:Peter.friese.itemis.de|Peter.friese.itemis.de]] 10:00, 30 April 2008 (EDT)
 
* We do NOT use Require-Bundle to import OSGi bundles, but instead use Import-Package. --[[User:Peter.friese.itemis.de|Peter.friese.itemis.de]] 10:00, 30 April 2008 (EDT)
 +
* Imports always have to include a version range. It is not allowed to import any version of a package/bundle [[User:B.kolb.kolbware.de|B.kolb.kolbware.de]] 10:30, 2 Mai 2008 (EDT)
  
 
== Logging and Tracing ==
 
== Logging and Tracing ==
Line 62: Line 66:
 
== Testing ==
 
== Testing ==
 
* Unit tests reside in a separate plug-in named ''<name of the plug-in to be tested>.tests'' --[[User:Jan.koehnlein.itemis.de|Jan.koehnlein.itemis.de]] 09:00, 30 April 2008 (EDT)
 
* Unit tests reside in a separate plug-in named ''<name of the plug-in to be tested>.tests'' --[[User:Jan.koehnlein.itemis.de|Jan.koehnlein.itemis.de]] 09:00, 30 April 2008 (EDT)
 +
* Unit tests may also reside in a fragment to a plugin named ''<name of the plug-in to be tested>.tests'' [[User:B.kolb.kolbware.de|B.kolb.kolbware.de]] 10:30, 2 Mai 2008 (EDT)
 
* Unit tests should test a single feature only. Avoid tests that depend on a large number of features. Tests will be far easier to maintain. --[[User:Jan.koehnlein.itemis.de|Jan.koehnlein.itemis.de]] 08:51, 30 April 2008 (EDT)
 
* Unit tests should test a single feature only. Avoid tests that depend on a large number of features. Tests will be far easier to maintain. --[[User:Jan.koehnlein.itemis.de|Jan.koehnlein.itemis.de]] 08:51, 30 April 2008 (EDT)
 
* Never release before all tests are green on the build server. --[[User:Jan.koehnlein.itemis.de|Jan.koehnlein.itemis.de]] 08:51, 30 April 2008 (EDT)
 
* Never release before all tests are green on the build server. --[[User:Jan.koehnlein.itemis.de|Jan.koehnlein.itemis.de]] 08:51, 30 April 2008 (EDT)
 
* If a test cannot be fixed, it is either obsolete or something is terribly wrong. Delete obsolete tests, fix all others. Never ignore failing tests. --[[User:Jan.koehnlein.itemis.de|Jan.koehnlein.itemis.de]] 09:14, 30 April 2008 (EDT)
 
* If a test cannot be fixed, it is either obsolete or something is terribly wrong. Delete obsolete tests, fix all others. Never ignore failing tests. --[[User:Jan.koehnlein.itemis.de|Jan.koehnlein.itemis.de]] 09:14, 30 April 2008 (EDT)
 
* All tests must also succeed on the build server. --[[User:Jan.koehnlein.itemis.de|Jan.koehnlein.itemis.de]] 09:14, 30 April 2008 (EDT)
 
* All tests must also succeed on the build server. --[[User:Jan.koehnlein.itemis.de|Jan.koehnlein.itemis.de]] 09:14, 30 April 2008 (EDT)
 +
* As a result, all tests have to run in an eclipse / osgi environment. [[User:B.kolb.kolbware.de|B.kolb.kolbware.de]] 10:30, 2 Mai 2008 (EDT)
  
 
== Build ==
 
== Build ==
Line 74: Line 80:
 
== Documentation ==
 
== Documentation ==
 
* In the root folder of each project, we place a readme.txt file that explains in one or two short sentences the purpose of the project. --[[User:Peter.friese.itemis.de|Peter.friese.itemis.de]] 10:14, 30 April 2008 (EDT)
 
* In the root folder of each project, we place a readme.txt file that explains in one or two short sentences the purpose of the project. --[[User:Peter.friese.itemis.de|Peter.friese.itemis.de]] 10:14, 30 April 2008 (EDT)
 +
* In the root folder of each project, we place an about.html file that explains in one or two short sentences the purpose of the project. -[[User:B.kolb.kolbware.de|B.kolb.kolbware.de]] 10:30, 2 Mai 2008 (EDT)
 
* User documentaton will be held in the Eclipse Wiki. Before releasing, we will scrape the current contents of the documentation wiki, transform it to DocBook and then transform it to PDF and Eclipse Help. (This has yet to be engineered. Check whether https://textile-j.dev.java.net/builds/net.java.textilej/latest/help/Textile-J%20User%20Guide.html#TextileConversion will work for us). --[[User:Peter.friese.itemis.de|Peter.friese.itemis.de]] 10:14, 30 April 2008 (EDT)
 
* User documentaton will be held in the Eclipse Wiki. Before releasing, we will scrape the current contents of the documentation wiki, transform it to DocBook and then transform it to PDF and Eclipse Help. (This has yet to be engineered. Check whether https://textile-j.dev.java.net/builds/net.java.textilej/latest/help/Textile-J%20User%20Guide.html#TextileConversion will work for us). --[[User:Peter.friese.itemis.de|Peter.friese.itemis.de]] 10:14, 30 April 2008 (EDT)
  
Line 79: Line 86:
 
* GUI design: SWT Designer --[[User:Peter.friese.itemis.de|Peter.friese.itemis.de]] 09:39, 30 April 2008 (EDT)
 
* GUI design: SWT Designer --[[User:Peter.friese.itemis.de|Peter.friese.itemis.de]] 09:39, 30 April 2008 (EDT)
 
* Bug hunting: FindBugs (triggered manually on the client, but run automatically on the build server) --[[User:Peter.friese.itemis.de|Peter.friese.itemis.de]] 09:39, 30 April 2008 (EDT)
 
* Bug hunting: FindBugs (triggered manually on the client, but run automatically on the build server) --[[User:Peter.friese.itemis.de|Peter.friese.itemis.de]] 09:39, 30 April 2008 (EDT)
 +
* Bug hunting: CodePro AnalytiX? [[User:B.kolb.kolbware.de|B.kolb.kolbware.de]] 10:30, 2 Mai 2008 (EDT)
 
* Ensuring architectural constraints: SonarJ --[[User:Peter.friese.itemis.de|Peter.friese.itemis.de]] 09:39, 30 April 2008 (EDT)
 
* Ensuring architectural constraints: SonarJ --[[User:Peter.friese.itemis.de|Peter.friese.itemis.de]] 09:39, 30 April 2008 (EDT)
 
* Profiling: YourKit --[[User:Peter.friese.itemis.de|Peter.friese.itemis.de]] 09:39, 30 April 2008 (EDT)
 
* Profiling: YourKit --[[User:Peter.friese.itemis.de|Peter.friese.itemis.de]] 09:39, 30 April 2008 (EDT)

Revision as of 04:43, 2 May 2008

oAW Developer Guidelines

The purpose of this page is to

  • centrally collect suggestions for policies and procedures for the development of openArchitectureWare 5
  • agree upon policies and procedures
  • provide new developers an easier start

Feel free to add your own suggestions and mark them with your name to make discussions easier.

Don't correct other user's suggestions (except typos). We should first collect ideas and then discuss critical issues.

It's not our objective to establish a heavy-weight process for oAW development. Make sure your suggestions are not to restrictive to keep oAW agile.

If some of these suggestions appear trivial or common sense to you, they might not be for others (especially new developers). So please ignore them gracefully unless you disagree.


Platform

  • Code must comply to Java 5 --Jan.koehnlein.itemis.de 08:51, 30 April 2008 (EDT)
  • In order to ensure we only use Java 5, all projects get a project specific compiler setting. --Peter.friese.itemis.de 10:03, 30 April 2008 (EDT)
  • Target platform is Eclipse 3.3 (4?) --Jan.koehnlein.itemis.de 08:51, 30 April 2008 (EDT)
  • Target standalone environment is Equinox, however it should be possible to run outside of OSGi as well B.kolb.kolbware.de 10:30, 2 Mai 2008 (EDT)

Coding

  • Internal packges must have internal in their name --Jan.koehnlein.itemis.de 08:56, 30 April 2008 (EDT)
  • Internal packages must have the internal right before the last segment of the plugin name: org.eclipse.xpand -> org.eclipse.internal.xpand B.kolb.kolbware.de 10:30, 2 Mai 2008 (EDT)
  • If you add a (source-)folder make sure to update build.properties. --Jan.koehnlein.itemis.de 08:56, 30 April 2008 (EDT)
  • Generated code should always reside in separate folder clearly marked as generated, such as src-gen or emf-gen. I'd prefer to even generate code into spearate plug-ins, as some files, like MANIFEST.MF cannot be merged. --Jan.koehnlein.itemis.de 09:04, 30 April 2008 (EDT)
  • The name of Java packages in plug-in should start with the name of the plug-in. --Jan.koehnlein.itemis.de 09:16, 30 April 2008 (EDT)
  • Wherever possible, IDs for Eclipse extensions should take the same name as the corresponding class. --Peter.friese.itemis.de 09:46, 30 April 2008 (EDT) E.g.
  class="org.openarchitectureware.core.properties.MetamodelContributorsPropertyAndPreferencePage"  
  id="org.openarchitectureware.core.properties.MetamodelContributorsPropertyPage"
  • All code has to be written with an OSGi environment in mind (classloading, reflection) B.kolb.kolbware.de 10:30, 2 Mai 2008 (EDT)


Formating

  • In order to make for a homogeneous look of the source code, we use the built-in Eclipse formatter (with slight adoptions if neccessary) as far as possible. --Peter.friese.itemis.de 09:34, 30 April 2008 (EDT)
  • We use TABS instead of SPACES. --Peter.friese.itemis.de 09:34, 30 April 2008 (EDT)
  • Curly braces will be places at the end of a line, not on a separate line. --Peter.friese.itemis.de 09:34, 30 April 2008 (EDT)

Code Repository

  • Everything that is checked into the repository must compile and must not break the build. --Jan.koehnlein.itemis.de 08:51, 30 April 2008 (EDT)
  • If you change code, make sure the unit tests are OK before you commit. --Jan.koehnlein.itemis.de 08:51, 30 April 2008 (EDT)
  • Avoid checking in generated code. Find out how to automtically run the generator on the build server. --Jan.koehnlein.itemis.de 09:09, 30 April 2008 (EDT)

Plug-ins

  • We maintain one team project set in the CVS that is always up-to-date. --Jan.koehnlein.itemis.de 08:51, 30 April 2008 (EDT)
  • We maintain an additional project set for anonymous access to the CVS (needed for non-committers). --Peter.friese.itemis.de 10:02, 30 April 2008 (EDT)
  • PSFs should be exported with working sets included. --Peter.friese.itemis.de 10:02, 30 April 2008 (EDT)
  • A Plug-in's ID must be the same as the project's name. --Jan.koehnlein.itemis.de 08:51, 30 April 2008 (EDT)
  • Separate UI code and non-UI code in different plug-ins. --Jan.koehnlein.itemis.de 08:51, 30 April 2008 (EDT)
  • If you add a plug-in, you must add it to the team project set. --Jan.koehnlein.itemis.de 08:51, 30 April 2008 (EDT)
  • If you add a plug-in, add it to at least one feature. --Jan.koehnlein.itemis.de 08:51, 30 April 2008 (EDT)
  • The name of a feature should always end with .feature. --Jan.koehnlein.itemis.de 08:57, 30 April 2008 (EDT)
  • The ID of a feature has to be equivalent with the 'main' plugin in the feature. So the feature name is the main plugin name + .feature
  • We need a way to communicate the addition of stuff to the project sets so everybody gets automatically notified and can check out the additional plug-ins. Suggestion: have Nick write a tool that scans .psf files for changes and notifies all developers of the respective module about this addition. --Peter.friese.itemis.de 09:52, 30 April 2008 (EDT)
  • We do NOT use Require-Bundle to import OSGi bundles, but instead use Import-Package. --Peter.friese.itemis.de 10:00, 30 April 2008 (EDT)
  • Imports always have to include a version range. It is not allowed to import any version of a package/bundle B.kolb.kolbware.de 10:30, 2 Mai 2008 (EDT)

Logging and Tracing

Testing

  • Unit tests reside in a separate plug-in named <name of the plug-in to be tested>.tests --Jan.koehnlein.itemis.de 09:00, 30 April 2008 (EDT)
  • Unit tests may also reside in a fragment to a plugin named <name of the plug-in to be tested>.tests B.kolb.kolbware.de 10:30, 2 Mai 2008 (EDT)
  • Unit tests should test a single feature only. Avoid tests that depend on a large number of features. Tests will be far easier to maintain. --Jan.koehnlein.itemis.de 08:51, 30 April 2008 (EDT)
  • Never release before all tests are green on the build server. --Jan.koehnlein.itemis.de 08:51, 30 April 2008 (EDT)
  • If a test cannot be fixed, it is either obsolete or something is terribly wrong. Delete obsolete tests, fix all others. Never ignore failing tests. --Jan.koehnlein.itemis.de 09:14, 30 April 2008 (EDT)
  • All tests must also succeed on the build server. --Jan.koehnlein.itemis.de 09:14, 30 April 2008 (EDT)
  • As a result, all tests have to run in an eclipse / osgi environment. B.kolb.kolbware.de 10:30, 2 Mai 2008 (EDT)

Build


Documentation

Additional Tools

Back to the top