Contributing Guide

Learn how to contribute code to iDempiere

First off, thanks for taking the time to contribute! This guide will help you understand the contribution workflow and best practices.

Before You Start

Before contributing, make sure that you:

1. Read our Code of Conduct
2. Review the Contributing to iDempiere’s core guide for coding conventions and guidelines
3. Join our Mattermost to discuss your contribution

Reporting Bugs

Before Submitting a Bug Report

1. Check the latest version

   Verify you can reproduce the problem in the latest version of iDempiere.

2. Search existing issues

   Check if the bug was already reported by searching JIRA Issues.

   If you find a Closed issue that seems like the same thing you’re experiencing, open a new issue and include a link to the original issue.

3. Check the FAQs

   Review the FAQs on the forum for common questions and problems.

4. Test on test sites

   Try to reproduce the bug on one of the test servers before creating a ticket.

How to Submit a Bug Report

Bugs are tracked as JIRA issues. Create a new issue and include:

Title and Description

• Use a clear and descriptive title that identifies the problem
• Describe the exact steps to reproduce the problem in as many details as possible
• Provide specific examples to demonstrate the steps

Expected vs Actual Behavior

• Describe the behavior you observed after following the steps
• Explain which behavior you expected to see instead and why
• Point out what exactly is the problem with the observed behavior

Supporting Evidence

• Include screenshots and videos if possible
• If iDempiere crashed, include a crash report with stack trace from log files
• If related to performance or memory, include valid numbers
• Reproduce with Garden data when possible

Context Information

• Can you reproduce on test sites?
• Did the problem start recently after an update?
• Which version(s) are affected?
• Can you reliably reproduce the issue?

Security Vulnerabilities: Do not open JIRA tickets for security vulnerabilities. Instead, refer to our security policy.

Suggesting Enhancements

Before Submitting an Enhancement

1. Discuss in the forum

   Suggest your change in the public forum. Do not open an issue on JIRA until you have collected positive feedback about the change.

   JIRA issues are primarily intended for bug reports and fixes.

2. Search for existing suggestions

   Check if there’s already a ticket that provides or suggests that enhancement.

3. Consider plugin approach

   Determine if the enhancement should be in core or implemented as a community plugin.

How to Submit an Enhancement Suggestion

Enhancement suggestions are tracked as JIRA issues. Include:

• A clear and descriptive title
• Step-by-step description of the suggested enhancement in as many details as possible
• Specific examples to demonstrate the steps
• Current behavior vs expected behavior
• Explanation of why this enhancement would be useful to most iDempiere users

Contributing Code

iDempiere uses a forking workflow for code contributions. Read the detailed Fork and Branch Git Workflow guide for more information.

Contribution Workflow

1. Create your personal fork

   Fork the iDempiere repository on GitHub to your personal account.

2. Clone your fork

   Clone your fork to your local machine:

   git clone https://github.com/YOUR-USERNAME/idempiere.git
   cd idempiere
   
3. Add upstream remote

   Add the upstream repository to keep your fork synchronized:

   git remote add upstream https://github.com/idempiere/idempiere.git
   
4. Synchronize with upstream

   Before creating a new branch, sync your local repository with upstream:

   git fetch upstream
   git checkout master
   git merge upstream/master
   
5. Create a feature branch

   Create a new branch for your work. Use a descriptive name:

   git checkout -b IDEMPIERE-####-descriptive-name
   

   Replace #### with your JIRA ticket number.

6. Make your changes

   Implement your changes following the code standards.

   Always follow iDempiere’s coding conventions and guidelines.

7. Test thoroughly

   Test your changes thoroughly. See the Testing Guide for details.

   • Write unit tests when appropriate
   • Test with Garden World data
   • Verify no regressions
8. Commit your changes

   Create a commit using the iDempiere standard message format:

   git add .
   git commit -m "IDEMPIERE-[####] [Ticket Description]"
   

   Commit Message Format: IDEMPIERE-[####] [Ticket Description]

   Example: IDEMPIERE-1234 Fix tax calculation for EU countries

9. Push to your fork

   Push your commit to your fork:

   git push origin IDEMPIERE-####-descriptive-name
   
10. Create a Pull Request

    Navigate to GitHub in your web browser and create a Pull Request:

    1. Go to your fork on GitHub
    2. Click “Compare & pull request” button
    3. Provide a clear description of your changes
    4. Reference the JIRA ticket number
    5. Submit the pull request
11. Document new features

    If the change is big and adds new functionality, document the modifications and new features and add this documentation to the new features wiki.

Pull Request Guidelines

• Keep pull requests focused on a single issue or feature
• Include the JIRA ticket number in the PR title and description
• Provide a clear description of what the PR does
• Include screenshots or videos for UI changes
• Ensure all tests pass
• Respond to review comments promptly

Contributing Plugins

If you wrote a plugin that is valuable for the community:

1. Read our Plugin Guidelines
2. Add your plugin to the available plugins site

If the community or its leaders find that your plugin does not follow the guidelines, is disrupting, or needs further support from a specific implementing company to use it, the project leaders are entitled to remove the plugin from the Available plugins list.

Contributing to Documentation

We welcome contributions to improve iDempiere documentation. Contact the team to learn more about contributing to documentation.

Getting Help

Questions About Source Code

Ask any question about how to use iDempiere in the public forum.

Questions About Contributing

Join our Mattermost Support Channel to ask questions about contributing.

Recognition

iDempiere is a volunteer effort, and we appreciate every contribution. Contributors are recognized on the GitHub contributors page.

Thanks for contributing to iDempiere!

Next Steps

Code Standards

Review coding conventions and best practices

Testing Guide

Learn about writing and running tests