Skip to main content
We welcome contributions to our source code, documentation, and translations. The following guidelines and recommendations enable the community to synchronize actions and provide a blueprint for seamless, non-intrusive collaboration.

Version control

Learn about the Git-based version control conventions used across all Oro projects, how to submit pull requests, and how to write good commit messages.

Code style

Code style conventions for PHP, JavaScript, SCSS, and more used in all Oro projects.

Translations

Contribute translations for Oro applications via Crowdin. Learn how to join the translation team and submit your work.

Documentation

Understand the documentation structure, reStructuredText syntax, and the workflow for publishing new topics.

Logging conventions

Standards for using Monolog in Oro applications, including log levels, message format, and context guidelines.

​
Contributor license agreement

Signing the Contributor License Agreement (CLA) is a prerequisite for having your pull request accepted. You only need to sign it once — it covers all Oro open-source projects. If you are submitting a pull request for the first time, the orocla robot will automatically add a reminder to your pull request.

​
Version control

​
Git and tools

Git is the official version control system used for Oro projects. GitHub is the main collaborative development tool. Common tools for managing Git repositories include:
  • CLI git tools
  • PhpStorm Git Integration plugin
  • SourceTree
  • SmartGit

​
Submitting a pull request

1

Search for existing issues

Search GitHub for an open or closed pull request that relates to your submission. Avoid duplicating effort.
2

Sign the CLA

Sign the Contributor License Agreement before submitting. The CLA must be signed for any code or documentation changes to be accepted.
3

Fork and branch

Fork the relevant Oro repository on GitHub and create a feature branch for your changes.
4

Make your changes

Implement your fix or enhancement, following the code style guidelines and writing appropriate tests.
5

Write a commit message

Include a clear summary and a list of performed actions. Example format:
<Commit summary>

- <action 1>
- <action 2>
- <action 3>
6

Submit the pull request

Open a pull request against the target Oro repository on GitHub. The orocla robot will verify your CLA status.

​
Code style

Standard: PSR-2 is used as the base coding standard.Line endings: LF (\n) — Unix and macOS style.DocBlocks: Required for every class and method you create or modify where the name does not fully reflect purpose, or parameter/return types cannot be defined in PHP code.
/**
 * Returns the products associated with the provided line item.
 *
 * @param int|LineItemInterface Integer ID of the line item or a line item object.
 * @return null|Product[] The array of associated products or null.
 */
public function getProductsForLineItem($lineItem): ?array;
Tools: PHP CodeSniffer and PHP Mess Detector are used on CI. Run them locally before submitting.
Configure PHP CodeSniffer in PHPStorm using the phpcs.xml from the platform repository. See PHPStorm documentation for setup instructions.

​
Deprecation annotations

@deprecated annotations may be used in maintenance branches to mark elements that will be removed in an upcoming LTS version. Always include the target version in the comment. 
/**
 * @deprecated Will be removed in version 4.2, use getSanitizedValues() instead.
 */
public function getValueContainers(): array
@todo, //TODO, and similar forward-looking annotations are not allowed. Create a tracked issue instead.

​
Translations

1

Join the translation team

Sign in or register at Crowdin. Open the OroCommerce project and click Join next to your target language. Submit a brief reason for joining. You will receive an approval email.
For OroCRM and OroPlatform translations, use their dedicated projects: OroCRM and OroPlatform.
2

Submit translations

Open the project via the Get Involved link in your Crowdin invite email. Select your target language, then choose a YAML translation file organized by bundle (e.g., OroCatalogBundle/messages.yml). Submit your translation. After submission, it is queued for proofreading.
3

Wait for approval

Other translators can vote on your translation. Once approved, it is marked with a green check mark. Approved translations are merged to the Oro application once per day.
4

Enable the language in the application

In the Oro application, navigate to System > Localization > Languages. If your target language is not listed, click Add Language. Import the translation by clicking the download icon and then Install.

​
Contact the translation team

Use the contact link in the Owner section of the OroCommerce project in Crowdin to report issues such as:
  • Your approved translation has not appeared in the application after one day.
  • Your translation has not been approved after more than seven days.
  • You want to help proofread a target language.

​
Documentation

1

Review the license and sign the CLA

Documentation use is subject to the CC-BY-NC-SA 4.0 license. Sign the CLA before submitting changes.
2

Fork the documentation repository

For small changes, use the Edit this file button in the GitHub UI. For larger changes, fork and clone the Oro documentation repository.
3

Make your changes

Documentation is written in reStructuredText and published with Sphinx. Follow the file naming conventions:
  • Use lowercase letters and Arabic numbers only
  • Separate words with dashes, not underscores (e.g., file-naming-conventions.rst)
  • Save files with .rst extension
4

Build and test locally

Install Docker and run:
docker bake --load
This generates the documentation in ./_build/html.
5

Submit a pull request

Create a pull request in the Oro documentation repository. After review, your changes will be merged and published.

​
File naming and structure

Documentation is organized in a tree hierarchy. Sections of the same level reside in the same folder. 
+ user/
    - index.rst
    + back-office/
        - topic-1.rst
        - topic-2.rst
+ backend/
    - index.rst
    + api/
        - endpoints.rst
- index.rst

​
Logging conventions

Use Monolog (PSR-3 LoggerInterface) for all logging in Oro applications.
LevelWhen to use
EMERGENCYSystem is unusable
ALERTImmediate action required (e.g., site is down, database unavailable)
CRITICALApplication component unavailable; unhandled exceptions causing 500 errors
ERRORRuntime errors not requiring immediate action but needing investigation
WARNINGDisturbing situations that are not errors (e.g., deprecated API usage, partial batch processing)
NOTICESignificant business operations completed successfully (e.g., import complete, payment sent)
INFOEvents of moderate significance (e.g., user login, workflow transition)
DEBUGDetailed debug information for events already logged at higher levels
  • Messages should be short, human-readable descriptions of the action.
  • Put variable data in the context array, not in the message string.
  • Use {placeholder} syntax in messages and match keys in the context array.
  • Use the exception key to pass Exception objects in context.
  • Never log sensitive data such as user credentials or payment information.
$logger->debug(
    'Authentication failure, forward triggered.',
    ['failure_path' => $path]
);
  • Inject the logger via constructor or LoggerAwareInterface.
  • Each independent component should use its own channel with the oro_ prefix.
  • When using LoggerAwareInterface, guard every logger call with a null check.
if (null !== $this->logger) {
    $this->logger->debug($message, $context);
}
Constructor-injected logger:
catch (\Exception $e) {
    $this->logger->error($message, ['exception' => $e]);
    // recover
}
LoggerAwareInterface:
catch (\Exception $e) {
    if (null !== $this->logger) {
        $this->logger->error($message, ['exception' => $e]);
    }
    // recover
}
Never catch exceptions silently without logging them. Symfony handles uncaught exceptions automatically, so do not catch just for logging.

Build docs developers (and LLMs) love

Get started for freeTalk to us