Project: MuleSoft (Orchestration & Management / API Gateway)
File: CONTRIBUTING.md

Really, thank you. Thank you for taking some of your precious time helping the Mule ESB project move forward. This guide will help you get started with Mule ESB's development environment. You'll also find the set of rules you're expected to follow in order to submit improvements and fixes to Mule ESB. In this guide you will find: - - - - - - -- Mule is a powerful and complex project. Before contributing to the Mule source code, it's important to understand the domain of the enterprise integration, Mule Runtime from the user point of view and the different mechanisms to extend Mule. There are a number of sources you can use to understand better Mule and its forthcoming features: MuleSoft's . The fastest way of knowing about new features in mule. 's twitter account. You might also want to check the hashtag. , the official documentation around usage of Mule Runtime. The books and . Both are excellent resources to understand how to use and extend Mule. If you are here reading this document, you probably have already in mind a new feature or a bug fix to work on. This is great, however there could be other members of the community with the same idea. Before you begin, please take a few minutes to review community meeting points to make sure someone else hasn't already taken on your challenge: Review to see if a bug has already been logged. Follow the chatter to see if anyone else has begun to resolve the problem or initiate the improvement. Scan to see if there is already a proposed solution for your problem. If, in the above-listed resources, no-one else has initiated your improvement or fix, log the issue by creating a . JIRA issues a identifier for your issue; keep this handy as you will use it to create a branch later if you decide to fix it yourself. Mule ESB has two different extension mechanisms for writing modules and connectors. Avoiding to add functionality to this project and rather use one of those mechanisms to extend Mule is probably the more favorable option. It is therefor important to understand those two extension mechanisms. The first and more intuitive mechanism for extensions is the , an annotation based framework for easy construction of extensions. The second choice is to extend mule through the mechanism. Now we should understand Mule and the enterprise integration domain. At the same time we should know the different extension mechanisms of Mule. While getting ready to contribute to any piece of software we will need to install number of prerequisites, we will need also to obtain the preexisting source code there could be. In this section we will follow some installation steps for the prerequisites and also we will download the source code. Before you get started, you need to set yourself up with an environment in which to develop Mule. Your dev environment needs three things: a Java SDK, a recent version of Maven, an integration development environment (IDE), and new branch of code to work on. If you are working with Windows or Linux, install Java SE 8u152 or a later update on your local drive. It can be downloaded from

If you are working on a Mac, simply confirm that the JDK shipped with your Mac OS X is Java SE Development Kit 8 (also known as Java SE 8u152) or a later update using the command `java -version`, then skip to step 4 below: Create an environment variable called `JAVA_HOME`, setting it to the directory in which you installed the JDK. Update the PATH environment variable so that it includes the path to JDK binaries. Add the following line to the PATH variable: Windows: `%JAVA_HOME%/bin` Linux or Mac OS X: `$JAVA_HOME/bin` Download the Maven distribution from the , then unpack it to a convenient folder on your local drive. Mule requires Maven version >= 3.3.9. Create an environment variable called `M2_HOME`, then set it to the folder into which you unpacked Maven. Update the `PATH` environment variable to include the path to Maven binaries. Windows: add the following line to the `PATH` variable: `%M2_HOME%/bin` Mac or Linux: add the following line to the `PATH` variable: `$M2_HOME/bin` Mule source code lives on Github. Complete the following procedure to locate the code and get it onto your local drive. If you're new to Git, consider reading to absorb the basics. Just want a Read-Only version of Mule source code? or log in to your github account. If you haven't already done so, on your local drive. Navigate to Mule's github page at: Click the Fork button at the top right corner of the page, then select your own git repository into which github inserts a copy of the repository. Prepare to clone your forked Mule Runtime repository from your github account to your local drive via a secure file transfer connection. As per git's recommendation, we advise using HTTPS to transfer the source code files to your local drive. However, if you prefer to establish a secure connection for transferring the files via SSH, follow git's procedure to . In the command line, create or navigate to an existing folder on your local drive into which you wish to store your forked clone of Mule source code. From the command line, execute one of the following: For HTTPS: `git clone https://github.com/<yourreponame>/mule` For SSH: `git clone git@github.com:<username>/<repo-name>.git` Add the upstream repository so that you can pull changes and stay updated with changes to the mule-3.x (i.e. main) branch. From the command line, execute one of the following: For HTTPS: `git remote add upstream https://github.com/mulesoft/mule.git` For SSH: `git remote add upstream git@github.com:mulesoft/mule.git` This is an excellent moment to read the guide to . A correct understanding of how the Mule project is organized and build is key for a productive development. We are ready to develop our improvements. However, instead of doing it manually we may want to configure an IDE for better productivity. We will do it in the next section. This section offers tips for importing and working on Mule source code in Eclipse or IntelliJ IDEA. There are no restrictions on the type of integration development environment you use to develop Mule, we simply chose to discuss the above-listed three as common IDEs. An open-source integration development platform, use Eclipse to modify or add to your cloned version of Mule source code. Download and install on your local drive. From the command line, in the directory into which you downloaded the Mule source code, enter the following command to generate the classpath and project files for each sub-project: `mvn

Before launching Eclipse, make the Maven repository known in Eclipse using the following command: `mvn -Declipse.workspace=/path/to/eclipse/workspace eclipse:configure-workspace`. Launch Eclipse, selecting the workspace you just "mavenized". Select File > Import. In the Import wizard, click to expand the General folder, then select Existing Projects into Workspace, then click Next. In the Select root directory field, use the Browse button to navigate to the directory into which you downloaded the cloned fork of Mule source code from your Github account. Ensure all Projects are checked, then click Finish. Eclipse imports the mule source code. Open source code files as you need to edit or add content. Click the Save icon to save locally. You can debug following these steps. There is also a more in-depth guide available in the . In Eclipse, select Window > Open Perspective > Other..., then select Java to open the Java Perspective. Select File > New > Java Project. You are creating a new project just for launching Mule. In the New Java Project wizard, select a Name for your project, such as Mule Launcher, then click Next. In the Java Settings panel of the wizard, select the Projects tab, then click Add. Click Select All, then click OK, then Finish. In the Package Explorer, right click your launcher project's name, then select Debug As > Debug Configurations... In the Debug Configurations wizard, double-click Java Application. In the Main class field, enter the following content: `org.mule.runtime.core.MuleServer` Click the Arguments tab. In the Program Arguments field, enter the following content: `-config <path to a Mule config>` Click Apply, then click Debug. Eclipse requests permission to switch to the Debug Perspective; click Yes to accept and open. You can now set breakpoints anywhere in any of the Java files in any of the Mule projects in the workspace. When you change java files and rebuild, the debugger hot swaps the rebuilt Java class file to the running Mule server. Note that you only need to follow the procedure above to set your Debug configurations once; thereafter, simply right-click the project name, then select Debug As > Java Application for subsequent debugging. From the command line, edit the `JPDA_OPTS` variable in the Mule startup script and specify the debugger port. Start the Mule server with the `-debug` switch. The server waits until a debugger attaches. In the Package Explorer in studio, right-click your Mule source code project's name, then select *Debug > Debug Configurations...* Double-click *Remote Java Application*. Under *Connection Properties, enter a value for Host and Port, then click Apply*. Click Debug. Eclipse requests permission to switch to the *Debug Perspective; click Yes* to accept and open. Use Maven to run unit test on your project using the following command: `mvn test`. In addition to the unit tests for each sub-project, the Mule parent project has a separate sub-project containing integration tests. These tests verify "macroscopic" functionality that could not be tested by any single sub-project alone. The table below lists a number of command-line parameters you can use to alter Eclipse's startup behavior, if you

| Parameter | Action | |:|:| | `-clean` | enables clean registration of plug-in (some plug-ins do not always register themselves properly after a restart) | | `-nosplash` | does not show Eclipse or plug-in splash screens | | `-showLocation` | allows you to explicitly set which JDK to use | | `-vm` | examples that come with the full Mule distribution | | `-vmargs` | allows you to pass in standard VM arguments | Use IntelliJ's IDEA integration platform to modify or add to your cloned Mule source code. and install IntelliJ IDEA. Open IDEA, then select *File > Open...* Browse to the directory into which you downloaded the Mule source code, then select the `pom.xml` file. Click *OK*. IDEA takes awhile to process all the pom.xml files. You can debug following these steps. There is also a more in-depth guide available in the . Start the Mule server with the `-debug` switch. The server waits until a debugger attaches. In IDEA, select Run > Edit Configurations... to open the Run/Debug Configurations window. Click Add New Configuration (plus sign), then select Remote. Enter a name for the configuration, then update the host and port values if required (You can use the default values, localhost:5005, for debugging a local mule instance). Click OK to start the debugging session. Use Maven to run unit tests on your project using the following command: `mvn test`. In addition to the unit tests for each sub-project, the Mule parent project has a separate sub-project containing integration tests. These tests verify "macroscopic" functionality that could not be tested by any single sub-project alone. We finally have everything ready to start writing code. Lets start with the code and also learn how to commit it in the next section. Working directly on the main version of Mule source code would likely result in merge conflicts with the original main. Instead, as a best practice for contributing to source code, work on your project in a feature branch. In order to create our feature branch we should follow these steps: From your local drive, create a new branch in which you can work on your bug fix or improvement using the following command: `git branch yourJIRAissuenumber`. Switch to the new branch using the following command: `git checkout yourJIRAissuenumber`. Now we should be able to make our very first compilation of the Mule Runtime source code. We just need to instruct Maven to download all the dependent libraries and compile the project, you can do so execution the following command Within the directory into which you cloned the Mule source code: `mvn -DskipTests install`. Note that if this is your first time using Maven, the download make take several minutes to complete. Windows and the local Maven repository In Windows, Maven stores the libraries in the .m2 repository in your home directory. For example, `C:\Documents and Settings\<username>\.m2\repository`. Because Java RMI tests fail where a directory name includes spaces, you must move the Maven local repository to a directory with a name that does not include spaces, such as `%M2_HOME%/conf` or `%USERPROFILE%/.m2` Now that you're all set with a local development environment and your own branch of Mule source code, you're ready get kicking! The following steps briefly outline the development lifecycle to follow to develop and commit your changes in preparation for submission. If you are using an IDE, make sure you read the previous section about . Review the documentation to ensure you adhere to source code standards, thus increasing the likelihood that your changes will be merged with the `mule-4.x` (i.e. main) source code. Import the Mule source code project into your IDE (if you are using one), then work on your changes, fixes or improvements. Debug and test your local version, resolving any issues that

Save your changes locally. Push your branch on your github repository. Refer to for details on how to commit your changes. Regularly update your branch with any changes or fixes applied to the mule-4.x branch. Refer to details below. To ensure that your cloned version of Mule source code remains up-to-date with any changes to the mule-4.x (i.e. main) branch, regularly update your branch to rebase off the latest version of the main. Pull the latest changes from the "upstream" main mule-4.x branch using the following commands: ```shell git fetch upstream git fetch upstream --tags ``` Ensure you are working with the main branch using the following command: ```shell git checkout mule-4.x ``` Merge the latest changes and updates from the main branch to your feature branch using the following command: ```shell git merge upstream/mule-4.x ``` Push any changes to the main to your forked clone using the following commands: ```shell git push origin mule-4.x git push origin --tags ``` Access your feature branch once again (to continue coding) using the following command: ```shell git checkout dev/yourreponame/bug/yourJIRAissuenumber ``` Rebase your branch from the latest version of the main branch using the following command: ```shell git rebase mule-4.x ``` Resolve any conflicts on your feature branch that may appear as a result of the changes to mule-4.x (i.e. main). Push the newly-rebased branch back to your fork on your git repository using the following command: ```shell git push origin dev/yourreponame/bug/yourJIRAissuenumber -f ``` Ready to submit your patch for review and merging? Initiate a pull request in github! Review the . Before any contribution is accepted, we need you to run the following notebook . This script will ask you to login to github and accept our Contributor's Agreement. That process creates an issue in our contributors project with your name. From the repo of your branch, click the Pull Request button. In the Pull Request Preview dialog, enter a title and optional description of your changes, review the commits that form part of your pull request, then click Send Pull Request (Refer to github's for submitting a pull request). Mule's core dev team reviews the pull request and may initiate discussion or ask questions about your changes in a Pull Request Discussion. The team can then merge your commits with the main where appropriate. We will validate acceptance of the agreement at this step. If you have made changes or corrections to your commit after having submitted the pull request, go back to the Pull Request page and update the Commit Range (via the Commits tab), rather than submitting a new pull request. This guide started with pointing to different around Mule and the Mule's on the net. These were useful to understand were Mule is moving to and to have contact mechanisms with the rest of the community for help or discussion. In order to set up our we got to . Once we had them ready, we downloaded the . At that point we were almost ready to develop improvements, we just needed to to develop or debug Mule code. Then we were finally ready to . We created our very own were we'll develop our improvement, then we learnt how to in order to be able to submit a to the main Mule Runtime repository Thank you one more time for taking some time understanding how to contribute to Mule Runtime.