Contributing to iDempiere Core

Overview

• What you’ll learn:
  • How the iDempiere open-source community is organized, including its governance model, communication channels, and contribution processes
  • How to use the GitHub fork-and-pull-request workflow to submit code contributions, and how to follow coding standards and review expectations
  • How to write migration scripts for core changes, participate in community activities, and build a path toward becoming a committer
• Prerequisites: Lesson 26 — Plugin Development Fundamentals, Lesson 27 — Building Your First Plugin, Git proficiency, Java development experience
• Estimated reading time: 22 minutes

Introduction

iDempiere is not just a piece of software — it is a community-driven open-source project with contributors from around the world. The platform’s continued evolution depends on people who report bugs, write documentation, submit code improvements, review pull requests, and help other users in forums and mailing lists. Contributing to iDempiere core is one of the most impactful ways to give back to the project and to influence the direction of the platform you depend on.

This lesson guides you through the practical process of contributing to iDempiere — from understanding the community structure and governance model to submitting your first pull request and navigating the review process. Whether your contribution is a one-line bug fix or a major feature, the process and standards described here apply.

The iDempiere Open-Source Community

iDempiere emerged from the ADempiere and Compiere heritage, launching as an independent project in 2012. It adopted OSGi modularity and modern development practices while preserving the comprehensive ERP functionality of its predecessors. The community is diverse, spanning consultants, developers, end users, and organizations across every continent.

Community Principles

• Meritocracy: Influence in the project is earned through contributions — code, documentation, support, and community building. No individual or company controls the project.
• Transparency: All decisions, discussions, and code changes happen in public channels (mailing lists, JIRA, GitHub). There are no private back-channel decisions about the project’s direction.
• Collaboration: The community values constructive collaboration, respectful discussion, and consensus-building. Code reviews are opportunities for learning, not criticism.

Governance Model

iDempiere follows a governance structure with defined roles:

• PMC (Project Management Committee): The governing body responsible for the strategic direction of the project, release management, and community stewardship. PMC members are experienced contributors who have demonstrated sustained commitment to the project.
• Committers: Developers with write access to the main repository. Committers can merge pull requests and make direct commits. Committer status is granted by the PMC based on a track record of quality contributions and community participation.
• Contributors: Anyone who contributes code, documentation, bug reports, or support. Contributors submit changes via pull requests that are reviewed and merged by committers.
• Users: The broader community of iDempiere users who provide feedback, report issues, and participate in discussions.

GitHub Repository Structure

The iDempiere source code is hosted on GitHub at github.com/idempiere/idempiere. Understanding the repository structure is essential for effective contribution.

Branch Strategy

• master (or main): The development branch where new features and improvements are merged. This branch represents the next release.
• release branches: When a release is being prepared, a branch is created from master (e.g., release-11). Only bug fixes are cherry-picked into release branches after the branch is created.

Project Structure

The repository contains multiple Eclipse/OSGi projects organized as a flat collection of directories:

• org.adempiere.base/: Core business logic, model classes, utilities.
• org.adempiere.ui.zk/: ZK web interface components.
• org.adempiere.server/: Server-side processes and schedulers.
• org.adempiere.report.jasper/: JasperReports integration.
• org.idempiere.test/: Test framework and test cases.
• migration/: SQL migration scripts organized by release version.
• org.adempiere.install/: Installation and setup utilities.

Fork and Pull Request Workflow

iDempiere uses the standard GitHub fork-and-pull-request workflow for contributions. Here is the step-by-step process.

Step 1: Fork the Repository

On GitHub, fork the idempiere/idempiere repository to your own GitHub account. This creates your personal copy where you can work freely without affecting the main repository.

Step 2: Clone and Set Up Your Development Environment

# Clone your fork
git clone https://github.com/YOUR_USERNAME/idempiere.git
cd idempiere

# Add the upstream remote to stay in sync
git remote add upstream https://github.com/idempiere/idempiere.git

# Verify remotes
git remote -v
# origin    https://github.com/YOUR_USERNAME/idempiere.git (fetch)
# origin    https://github.com/YOUR_USERNAME/idempiere.git (push)
# upstream  https://github.com/idempiere/idempiere.git (fetch)
# upstream  https://github.com/idempiere/idempiere.git (push)

Set up your IDE (Eclipse is the standard for iDempiere development) and import the projects according to the setup instructions in the repository’s documentation.

Step 3: Create a Feature Branch

Always work on a dedicated branch, never directly on master:

# Ensure your master is up to date
git checkout master
git pull upstream master

# Create a feature branch with a descriptive name
git checkout -b IDEMPIERE-XXXX-short-description

Name your branch after the JIRA ticket (described below) followed by a short description. This makes it easy to associate branches with issues.

Step 4: Make Your Changes

Implement your fix or feature. Follow the coding standards described later in this lesson. Make focused, cohesive changes — one logical change per pull request. If you are fixing a bug and notice an unrelated issue, address it in a separate pull request.

Step 5: Write Tests

Write automated tests for your changes in the org.idempiere.test project. Tests are required for most contributions and significantly increase the chances of your pull request being accepted. Test both the expected behavior (happy path) and edge cases (error conditions, boundary values).

Step 6: Create Migration Scripts (If Required)

If your change involves database modifications, you must include migration scripts (described in detail later in this lesson).

Step 7: Commit and Push

# Stage your changes
git add -A

# Commit with a meaningful message (see commit message guidelines)
git commit -m "IDEMPIERE-XXXX: Brief description of the change"

# Push to your fork
git push origin IDEMPIERE-XXXX-short-description

Step 8: Create the Pull Request

On GitHub, create a pull request from your feature branch to the idempiere/idempiere master branch. In the pull request description, include:

• A reference to the JIRA ticket (e.g., “Fixes IDEMPIERE-XXXX”).
• A clear description of what the change does and why.
• How to test the change (steps for reviewers to verify).
• Any migration notes or special considerations.
• Screenshots if the change affects the UI.

JIRA Issue Tracking

iDempiere uses JIRA for issue tracking. Every code contribution should be associated with a JIRA ticket.

Creating a JIRA Ticket

1. Navigate to the iDempiere JIRA instance.
2. Create a new issue with the appropriate type: Bug (for defects), Improvement (for enhancements to existing features), New Feature (for entirely new functionality), or Task (for maintenance and housekeeping).
3. Provide a clear title and detailed description. For bugs, include steps to reproduce, expected behavior, and actual behavior. For features, describe the use case and proposed solution.
4. Set the component and version fields appropriately.

Linking PRs to JIRA

Reference the JIRA ticket number in your commit messages and pull request title (e.g., IDEMPIERE-6123: Fix NPE in payment allocation when discount is zero). This creates automatic links between JIRA and GitHub, making it easy for reviewers and future developers to trace the context of any change.

Coding Standards and Conventions

Consistent code style across the project makes the codebase readable, maintainable, and reviewable. Follow these conventions for iDempiere contributions.

Java Coding Standards

• Formatting: Use tabs for indentation (not spaces). Follow the Eclipse default Java formatter settings used by the project. Configure your IDE to match before making changes — formatting differences create noisy diffs that obscure real changes.
• Naming: Follow standard Java naming conventions — camelCase for methods and variables, PascalCase for classes, ALL_CAPS for constants. Use descriptive names that convey intent.
• Comments: Write Javadoc for public methods and classes. Inline comments should explain why, not what — the code itself should be clear enough to show what it does.
• Null handling: Check for null values defensively, especially when working with database query results and user input. Use Util.isEmpty() for string checks.
• Logging: Use the CLogger class for logging. Log at appropriate levels — FINE for debugging details, INFO for significant operations, WARNING for recoverable errors, SEVERE for failures.

SQL Standards

• Use uppercase for SQL keywords (SELECT, FROM, WHERE).
• Use parameterized queries (prepared statements) — never concatenate user input into SQL strings.
• Write database-agnostic SQL where possible (compatible with both PostgreSQL and Oracle). If database-specific syntax is required, provide implementations for both databases.

Code Review Process

All contributions go through code review before being merged. Code reviews serve multiple purposes: catching bugs, ensuring code quality, knowledge sharing, and maintaining consistency across the codebase.

What Reviewers Look For

• Correctness: Does the code do what it claims to do? Are edge cases handled?
• Testing: Are there adequate tests? Do the tests cover the important scenarios?
• Style: Does the code follow the project’s coding standards?
• Performance: Are there potential performance issues (N+1 queries, unnecessary database calls, memory leaks)?
• Compatibility: Does the change work with both PostgreSQL and Oracle? Does it maintain backward compatibility?
• Migration: Are migration scripts provided for database changes? Are they correct and idempotent?
• Security: Are there potential security issues (SQL injection, improper access control, information disclosure)?

Responding to Review Feedback

When reviewers request changes:

• Respond to every comment — either make the requested change or explain why you disagree (with reasoning).
• Push additional commits to the same branch (do not force-push, as this makes it hard for reviewers to see what changed).
• Be patient — reviewers are volunteers contributing their time. Reviews may take days or weeks depending on the complexity and the reviewers’ availability.

How to Write Good Commit Messages

Good commit messages are essential for project history. Follow this format:

IDEMPIERE-XXXX: Short summary of the change (50 chars or less)

Longer description if needed. Explain the motivation for the change,
what problem it solves, and any important design decisions. Wrap
lines at 72 characters.

- Bullet points are acceptable for listing multiple changes
- Reference related tickets if applicable

• The first line is the subject: start with the JIRA ticket number, followed by a concise summary.
• Separate the subject from the body with a blank line.
• Use the imperative mood in the subject (“Fix bug” not “Fixed bug” or “Fixes bug”).
• The body explains why the change was made, not just what was changed (the diff shows the what).

Migration Scripts for Core Changes

When a contribution includes database changes (new tables, new columns, modified columns, new reference data), migration scripts must be provided. iDempiere uses SQL migration scripts that are executed during the upgrade process.

Migration Script Structure

-- Migration script location:
-- migration/iN.N/postgresql/YYYYMMDDHHMMSS_IDEMPIERE-XXXX.sql

-- Example: Adding a new column to C_BPartner
-- IDEMPIERE-6123 Add preferred communication channel to Business Partner

SELECT register_migration_script('YYYYMMDDHHMMSS') FROM dual;

-- Add column
ALTER TABLE C_BPartner ADD COLUMN PreferredChannel VARCHAR(2) DEFAULT 'EM';

-- Add to Application Dictionary
INSERT INTO AD_Column (AD_Column_ID, AD_Client_ID, AD_Org_ID, IsActive,
    Created, CreatedBy, Updated, UpdatedBy,
    Name, Description, AD_Table_ID, ColumnName, FieldLength,
    AD_Reference_ID, DefaultValue, IsKey, IsParent, IsMandatory,
    IsUpdateable, IsIdentifier, AD_Element_ID)
VALUES (get_next_id('AD_Column'), 0, 0, 'Y',
    now(), 100, now(), 100,
    'Preferred Channel', 'Preferred communication channel',
    291, 'PreferredChannel', 2,
    17, 'EM', 'N', 'N', 'N',
    'Y', 'N', get_next_id('AD_Element'));

-- Provide Oracle version as well
-- migration/iN.N/oracle/YYYYMMDDHHMMSS_IDEMPIERE-XXXX.sql

Migration Script Requirements

• Provide scripts for both PostgreSQL and Oracle databases.
• Scripts must be idempotent where possible — running the same script twice should not cause errors (use IF NOT EXISTS clauses, check before insert).
• Use the correct naming convention: YYYYMMDDHHMMSS_IDEMPIERE-XXXX.sql with the timestamp indicating the creation time.
• Include Application Dictionary updates (AD_Table, AD_Column, AD_Field, etc.) — do not just modify the database schema.
• Register the migration script with register_migration_script() so the system knows which scripts have been applied.

Testing Requirements for Contributions

The iDempiere project maintains a test suite in the org.idempiere.test bundle. Contributions should include tests whenever possible.

Writing Tests

// Example: Test for a bug fix in payment allocation
public class PaymentAllocationTest extends AbstractTestCase {

    @Test
    public void testAllocationWithZeroDiscount() {
        // Set up test data
        MBPartner bp = new MBPartner(Env.getCtx(), 0, getTrxName());
        bp.setName("Test Partner");
        bp.setIsCustomer(true);
        bp.saveEx();

        // Create and complete an invoice
        MInvoice invoice = createTestInvoice(bp, new BigDecimal("100.00"));
        completeDocument(invoice);

        // Create allocation with zero discount (the bug scenario)
        MAllocationHdr alloc = new MAllocationHdr(Env.getCtx(), true,
            Env.getContextAsDate(Env.getCtx(), "#Date"),
            116, "Test allocation", getTrxName());
        alloc.saveEx();

        MAllocationLine line = new MAllocationLine(alloc,
            new BigDecimal("100.00"),
            BigDecimal.ZERO,  // Zero discount - previously caused NPE
            BigDecimal.ZERO,
            BigDecimal.ZERO);
        line.setC_Invoice_ID(invoice.get_ID());
        line.saveEx();

        // This should not throw NPE (the fix)
        String result = alloc.completeIt();
        assertEquals(DocAction.STATUS_Completed, result);
        assertEquals(BigDecimal.ZERO, invoice.getOpenAmt());
    }
}

Community Communication

Active participation in community communication channels is essential for effective contribution.

Mailing Lists

The iDempiere mailing lists on Google Groups are the primary communication channels:

• idempiere-developers: Technical discussions about code, architecture, and development practices.
• idempiere-users: Functional discussions, user support, and implementation questions.

Forums and Wiki

The iDempiere wiki contains documentation, how-to guides, and architectural notes. Contributing to documentation is just as valuable as contributing code — perhaps more so, as good documentation helps many more people than a single bug fix.

iDempiere Conference

The annual iDempiere World Conference brings the community together for presentations, workshops, and networking. Attending (or presenting at) the conference is an excellent way to deepen your involvement and build relationships with other community members.

Becoming a Committer

Committer status is granted by the PMC based on demonstrated merit. There is no fixed checklist, but the following behaviors increase your chances:

• Consistent contributions: Regular, quality contributions over an extended period (months to years) demonstrate sustained commitment.
• Code quality: Submissions that consistently pass review with minimal changes demonstrate technical maturity.
• Community participation: Active participation in discussions, helping other users, reviewing pull requests, and contributing documentation.
• Domain expertise: Deep knowledge of specific areas of iDempiere (e.g., accounting engine, manufacturing, reporting) that makes your reviews and contributions particularly valuable.
• Reliability: Following through on commitments, responding to review feedback promptly, and being a dependable community member.

Intellectual Property and License

iDempiere is licensed under the GNU General Public License version 2 (GPLv2). When you contribute code to iDempiere, you are agreeing that your contribution will be distributed under this license.

Key License Considerations

• Copyleft: GPLv2 requires that derivative works also be distributed under GPLv2. If you modify iDempiere core code, your modifications must be open-sourced under the same license.
• Plugin exception: Plugins that interact with iDempiere through its public APIs and extension points (OSGi services, model validators, callouts) are generally considered separate works and can be distributed under different licenses. This is a critical distinction for commercial plugin developers.
• Contributor agreement: Ensure that you have the right to contribute the code you submit. If you are employed, your employer may have IP claims on code you write. Clarify this before contributing.
• Third-party code: Do not include code from other projects unless its license is compatible with GPLv2. Document the source and license of any third-party code included in your contribution.

Summary

Contributing to iDempiere is a rewarding way to improve the platform you depend on, build your professional reputation, and participate in a global open-source community. The key steps are:

• Create a JIRA ticket for your change.
• Fork the repository, create a feature branch, and implement your change following coding standards.
• Write tests and migration scripts as needed.
• Submit a pull request with a clear description and JIRA reference.
• Respond constructively to code review feedback.
• Participate in community discussions beyond just code contributions.

In the next lesson, we will explore real-world iDempiere deployments through case studies — learning from the successes and challenges of enterprise implementations across different industries.

# Clone 您的 fork
git clone https://github.com/YOUR_USERNAME/idempiere.git
cd idempiere

# 新增 upstream remote 以保持同步
git remote add upstream https://github.com/idempiere/idempiere.git

# 驗證 remotes
git remote -v
# origin    https://github.com/YOUR_USERNAME/idempiere.git (fetch)
# origin    https://github.com/YOUR_USERNAME/idempiere.git (push)
# upstream  https://github.com/idempiere/idempiere.git (fetch)
# upstream  https://github.com/idempiere/idempiere.git (push)

# 確保您的 master 是最新的
git checkout master
git pull upstream master

# 建立描述性名稱的功能分支
git checkout -b IDEMPIERE-XXXX-short-description

# 暫存您的變更
git add -A

# 使用有意義的訊息提交（見提交訊息指南）
git commit -m "IDEMPIERE-XXXX: Brief description of the change"

# 推送到您的 fork
git push origin IDEMPIERE-XXXX-short-description

IDEMPIERE-XXXX: Short summary of the change (50 chars or less)

Longer description if needed. Explain the motivation for the change,
what problem it solves, and any important design decisions. Wrap
lines at 72 characters.

- Bullet points are acceptable for listing multiple changes
- Reference related tickets if applicable

-- 遷移腳本位置：
-- migration/iN.N/postgresql/YYYYMMDDHHMMSS_IDEMPIERE-XXXX.sql

-- 範例：向 C_BPartner 新增欄位
-- IDEMPIERE-6123 Add preferred communication channel to Business Partner

SELECT register_migration_script('YYYYMMDDHHMMSS') FROM dual;

-- 新增欄位
ALTER TABLE C_BPartner ADD COLUMN PreferredChannel VARCHAR(2) DEFAULT 'EM';

-- 新增至 Application Dictionary
INSERT INTO AD_Column (AD_Column_ID, AD_Client_ID, AD_Org_ID, IsActive,
    Created, CreatedBy, Updated, UpdatedBy,
    Name, Description, AD_Table_ID, ColumnName, FieldLength,
    AD_Reference_ID, DefaultValue, IsKey, IsParent, IsMandatory,
    IsUpdateable, IsIdentifier, AD_Element_ID)
VALUES (get_next_id('AD_Column'), 0, 0, 'Y',
    now(), 100, now(), 100,
    'Preferred Channel', 'Preferred communication channel',
    291, 'PreferredChannel', 2,
    17, 'EM', 'N', 'N', 'N',
    'Y', 'N', get_next_id('AD_Element'));

-- 也提供 Oracle 版本
-- migration/iN.N/oracle/YYYYMMDDHHMMSS_IDEMPIERE-XXXX.sql

// 範例：付款配置錯誤修正的測試
public class PaymentAllocationTest extends AbstractTestCase {

    @Test
    public void testAllocationWithZeroDiscount() {
        // 設定測試資料
        MBPartner bp = new MBPartner(Env.getCtx(), 0, getTrxName());
        bp.setName("Test Partner");
        bp.setIsCustomer(true);
        bp.saveEx();

        // 建立並完成發票
        MInvoice invoice = createTestInvoice(bp, new BigDecimal("100.00"));
        completeDocument(invoice);

        // 建立折扣為零的配置（錯誤情境）
        MAllocationHdr alloc = new MAllocationHdr(Env.getCtx(), true,
            Env.getContextAsDate(Env.getCtx(), "#Date"),
            116, "Test allocation", getTrxName());
        alloc.saveEx();

        MAllocationLine line = new MAllocationLine(alloc,
            new BigDecimal("100.00"),
            BigDecimal.ZERO,  // 零折扣 - 之前導致 NPE
            BigDecimal.ZERO,
            BigDecimal.ZERO);
        line.setC_Invoice_ID(invoice.get_ID());
        line.saveEx();

        // 這不應拋出 NPE（修正）
        String result = alloc.completeIt();
        assertEquals(DocAction.STATUS_Completed, result);
        assertEquals(BigDecimal.ZERO, invoice.getOpenAmt());
    }
}

# フォークをクローン
git clone https://github.com/YOUR_USERNAME/idempiere.git
cd idempiere

# 同期を保つために upstream リモートを追加
git remote add upstream https://github.com/idempiere/idempiere.git

# リモートを確認
git remote -v
# origin    https://github.com/YOUR_USERNAME/idempiere.git (fetch)
# origin    https://github.com/YOUR_USERNAME/idempiere.git (push)
# upstream  https://github.com/idempiere/idempiere.git (fetch)
# upstream  https://github.com/idempiere/idempiere.git (push)

# master が最新であることを確認
git checkout master
git pull upstream master

# 説明的な名前のフィーチャーブランチを作成
git checkout -b IDEMPIERE-XXXX-short-description

# 変更をステージング
git add -A

# 意味のあるメッセージでコミット（コミットメッセージガイドライン参照）
git commit -m "IDEMPIERE-XXXX: Brief description of the change"

# フォークにプッシュ
git push origin IDEMPIERE-XXXX-short-description

IDEMPIERE-XXXX: Short summary of the change (50 chars or less)

Longer description if needed. Explain the motivation for the change,
what problem it solves, and any important design decisions. Wrap
lines at 72 characters.

- Bullet points are acceptable for listing multiple changes
- Reference related tickets if applicable

-- 移行スクリプトの場所：
-- migration/iN.N/postgresql/YYYYMMDDHHMMSS_IDEMPIERE-XXXX.sql

-- 例：C_BPartner に新しいカラムを追加
-- IDEMPIERE-6123 Add preferred communication channel to Business Partner

SELECT register_migration_script('YYYYMMDDHHMMSS') FROM dual;

-- カラムの追加
ALTER TABLE C_BPartner ADD COLUMN PreferredChannel VARCHAR(2) DEFAULT 'EM';

-- Application Dictionary に追加
INSERT INTO AD_Column (AD_Column_ID, AD_Client_ID, AD_Org_ID, IsActive,
    Created, CreatedBy, Updated, UpdatedBy,
    Name, Description, AD_Table_ID, ColumnName, FieldLength,
    AD_Reference_ID, DefaultValue, IsKey, IsParent, IsMandatory,
    IsUpdateable, IsIdentifier, AD_Element_ID)
VALUES (get_next_id('AD_Column'), 0, 0, 'Y',
    now(), 100, now(), 100,
    'Preferred Channel', 'Preferred communication channel',
    291, 'PreferredChannel', 2,
    17, 'EM', 'N', 'N', 'N',
    'Y', 'N', get_next_id('AD_Element'));

-- Oracle 版も提供
-- migration/iN.N/oracle/YYYYMMDDHHMMSS_IDEMPIERE-XXXX.sql

// 例：支払配賦のバグ修正テスト
public class PaymentAllocationTest extends AbstractTestCase {

    @Test
    public void testAllocationWithZeroDiscount() {
        // テストデータのセットアップ
        MBPartner bp = new MBPartner(Env.getCtx(), 0, getTrxName());
        bp.setName("Test Partner");
        bp.setIsCustomer(true);
        bp.saveEx();

        // 請求書の作成と完了
        MInvoice invoice = createTestInvoice(bp, new BigDecimal("100.00"));
        completeDocument(invoice);

        // ゼロ割引での配賦を作成（バグシナリオ）
        MAllocationHdr alloc = new MAllocationHdr(Env.getCtx(), true,
            Env.getContextAsDate(Env.getCtx(), "#Date"),
            116, "Test allocation", getTrxName());
        alloc.saveEx();

        MAllocationLine line = new MAllocationLine(alloc,
            new BigDecimal("100.00"),
            BigDecimal.ZERO,  // ゼロ割引 - 以前は NPE を引き起こした
            BigDecimal.ZERO,
            BigDecimal.ZERO);
        line.setC_Invoice_ID(invoice.get_ID());
        line.saveEx();

        // NPE をスローしないはず（修正）
        String result = alloc.completeIt();
        assertEquals(DocAction.STATUS_Completed, result);
        assertEquals(BigDecimal.ZERO, invoice.getOpenAmt());
    }
}