Contributing to Core

This tutorial is brought to you by Diego Ruiz and Thomas Bayen from BXService GmbH. If you have questions or improvement suggestions, feel free to write me an email

This is part of a list of all possible contributions, you can check those in Contributing to iDempiere.

The goal of this tutorial

The goal of this wiki is to show a way to develop improvements which are targeted to be pushed into the trunk. There are a lot of nice improvements and contributions that people have in mind and code. But they don't get into the trunk because of lack of some details.

Common Issues

Idempiere being a great open source project needs to have high quality standards. Pushing code into the core has several implications that have to be covered when a new development is done. Some of them are:

• It has to work in PostgreSQL and Oracle.
• A new functionality cannot break previous features. (This sounds obvious but it's easy to make this mistake if you don't test enough)
• Check the backward compatibility. If you find "unused" fields, assume that they can be used by people in different ways in many implementations.
• Comments, methods and variables MUST be in English.
  • Always think in the community peer reviewers - it's always better to comment code that is not easy to understand - but an excess of need for comments can mean that names or algorithms can be improved
• Big things or big changes require big documentation (manual, use cases, test cases)
• Mixing new features code and re-factoring code is hard to review. Please make different commits for both cases.
• When possible avoid the SQL Code, use the data model instead.

If people think only about satisfying their own needs without caring about community welfare, the code becomes untenable and to evolve it becomes more difficult or even impossible at some point.

So with that in mind, we decided to create this checklist to make it easier for everyone to contribute great code, be a part of this community and become known for continuous help and contributions.

How to Contribute

This is a checklist of the main/minimum things that should be done to contribute in the core:

• If you need to change the database check the Changing the database chapter first.

Note: If your development needs the database changes and you don't do this first. You will have to do it all over again

• Every commit must be related to a Jira ticket. Please do not mix commits, if the new code needed a refactoring of old code, create one patch for refactoring and one for the actual solution (This makes it easier for review).
• When you want to get data. The best way to do it is in the following order:
  • Model Classes. Most of the M classes in iDempiere have a get method to avoid reading from the database.
  • Query Class.
  • DB Class (DB.get())
  • And finally JDBC, only if it is really needed as the impact in the memory is greater than the approaches above.
• Java classes, methods and variable formats. Follow the java standards (meaningful names, camel case). The code should be indented to improve its readability and maintainability.
• Make sure each java class has the GPLv2 Header.
• I think the most important one is the collateral analysis of your code. Even if you changed one line that you think doesn't have a huge impact. Make sure to know where this change affects the behavior in other classes, where is it referenced, and test the corresponding cases to check that you're not injecting new bugs with your contribution.
• Make sure you don't fall in one of the Common Issues

When you have finished the previous steps create the patch with a commit message including the ticket number in JIRA so it updates automatically between the repository and the jira ticket.

Changing the database

• If the database was changed and official IDs are needed:
  • First you need to Manage the Centralized IDs
  • Then Generate the Migration Scripts
  • When generating a migration script is a good practice to set the right value for the DICTIONARY_ID_COMMENTS SysConfig key. The migration script will take it, while also helping other developers to know what is being worked on when they receive the email of an official ID assignment.
• When you have successfully created your migration scripts name them with this format: yyyymmddhhmm_ticket.sql
• Add at the end of both migration scripts the register line e.g: SELECT register_migration_script('201504180139_IDEMPIERE-2556.sql') FROM dual
• Copy the respective scripts into the PostgreSQL folder and the oracle folder (migration/i2.1z/...)

Changing the code

• When adding, removing or changing the signature of a public method. It's advised to regenerate the serialVersionUID.
• When changing the signature of a public method, better do an overload.

it helps others customize code or plugin can working.