Access Keys:
Skip to content (Access Key - 0)
Cancel    
Cancel   
 

Mule Contributors Guide

Mar 06, 2013 10:30

Janet Revell

Apr 11, 2014 15:28

Mulesoft Current Mule Documentation

Mule Contributors Guide

Mulesoft Documentation Page

Contents

Mule Contributors' Guide 

We're always interested in improvements, fixes and ideas that will help solve problems or code faster. If you're interested in contributing and making Mule even better, bring it on! Our source code lives on github and we welcome pull requests for fixes and innovations. Follow the steps in this Contributors' Guide to prepare and submit your contribution.

 

A  Checking Forums and JIRA

Before you begin, take a few minutes to review our bug-tracking system and our forum to make sure someone else hasn't already taken on your challenge.

  1. Review existing JIRAs to see if a bug has already been logged.
  2. Peruse the Mule forum chatter to see if anyone else has begun to resolve the problem or initiate the improvement.
  3. Scan StackOverflow to see if there is already a proposed solution for your problem. 
  4. If, in the above-listed resources, no-one else has initiated your improvement or fix, log the issue by creating a Mule JIRA.  JIRA issues a number to identify your issue; keep this number handy as you will use it to create a branch later in this procedure.

 

B  Getting the Source Code

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 Pro Git to absorb the basics.

 Just want a Read-Only version of Mule source code?
  1. Follow steps 2-6 below, just skip step 4.
  2. From the command line, execute the following to clone a read-only version of Mule source code directly from Mule's github repository: $ git clone git://github.com/mulesoft/mule.git
  1. Create or log in to your github account
  2. If you haven't already done so, set up git on your local drive.
  3. Navigate to Mule's github page at: https://github.com/mulesoft/mule.git

  4. 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.
  5. Prepare to clone your forked Mule ESB 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 generate SSH keys.
  6. 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.
  7. From the command line, execute one of the following:
    1. For HTTPS git clone https://github.com/<yourreponame>/mule
    2. For SSH git clone git@github.com:<username>/<repo-name>.git
  8. Add the upstream repository so that you can pull changes and stay updated with changes to the mule-3.x (i.e. master) branch. From the command line, execute one of the following:
    1. For HTTPS: git remote add upstream https://github.com/mulesoft/mule.git

    2. For SSH: git remote add upstream git@github.com:mulesoft/mule.git

 

C  Setting Up a Development Environment

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.

 JDK

  1. If you are working with Windows or Linux, install one of the following Java Development Kits on your local drive. If you are working on a Mac, simply confirm that the JDK shipped with your OSX matches one of the JDKs listed below  (java -version), then skip to step 4 below.
    • Java SE Development Kit Standard Edition 1.6.0_26 (also known as Java SE 6 Update 26)
    • Java SE Development Kit 7 (also known as Java SE 7u13)
  2. Create an environment variable called JAVA_HOME, setting it to the directory in which you installed the JDK. 
  3. 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: $JAVA_HOME/bin

Maven

  1. Download the Maven distribution from the Maven web site, then unpack it to a convenient folder on your local drive. 
  2. Create an environment variable called M2_HOME, then set it to the folder into which you unpacked Maven. 
  3. 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

IDE

  1. Select an integration development environment (IDE) to use to build your fix or improvement. You might consider using Studio, Mule's graphical IDE, Eclipse or IntelliJ. We touch more on the subject of working with Maven and an IDE later in this guide. 

Topic Branch, Dependencies and Artifacts

Working directly on the master version of Mule source code would likely result in merge conflicts with the original master. Instead, as a best practice for contributing to source code, work on your project in a topic branch. (The following commands apply to a UNIX-based OS; adjust appropriately for Windows.)

  1. 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 dev/yourreponame/bug/yourJIRAissuenumber
  2. Switch to the new branch using the following command: 
    git checkout dev/yourreponame/bug/yourJIRAissuenumber
  3. Within the directory into which you cloned the Mule source code, instruct Maven to download all the dependent libraries by using the following command: 
    mvn -DskipTests install  
    Note that if this is your first time using Maven, the download make take several minutes to complete.
  4. If you are using Mac or Linux, skip to the next step. 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
  5. If you are using a Mac OS, examine the contents of the $JAVA_HOME/jre/lib/security directory to confirm that the following two files are present:
    • local_policy.jar
    • US_export_policy.jar

    These two files prevent any problems regarding cryptology. If not present, download the Java Cryptology Extension (JCE) Unlimited Strength Jurisdiction Policy Files 6.0, then copy the files into the security directory identified above.

D  Developing Mule Source Code

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.

  1. Review Contributing to Mule Source Code Using an IDE and Contributing to Mule Source Code Using Maven to learn more about how to work in your newly set up development environment.
  2. Review the Mule Coding Conventions documentation to ensure you adhere to source code standards, thus increasing the likelihood that your changes will be merged with the mule-3.x (i.e. master) source code.
  3. Import the Mule source code project into your IDE, then work on your changes, fixes or improvements. 
  4. Debug and test your  local version, resolving any issues that arise. 
  5. Save your changes locally.
  6. Prepare your changes for a Pull Request by first squashing your changes into a single commit on your branch using the following command: 
    git rebase i mule3.x
  7. Push your squashed commit to your branch on your github repository. Refer to Git's documentation for details on how to commit your changes.
  8. Regularly update your branch with any changes or fixes applied to the mule-3.x branch. Refer to details below.


Updating Your Branch

To ensure that your cloned version of Mule source code remains up-to-date with any changes to the mule-3.x (i.e. master) branch, regularly update your branch to rebase off the latest version of the master.  

  1. Pull the latest changes from the "upstream" master mule-3.x branch using the following commands:
    git fetch upstream
    git fetch upstream --tags 
  2. Ensure you are working with the master branch using the following command:
    git checkout mule-3.x
  3. Merge the latest changes and updates from the master branch to your topic branch using the following command:
    git merge upstream/mule-3.x
  4. Push any changes to the master to your forked clone using the following commands:
    git push origin mule-3.x
    git push origin --tags
  5. Access your topic branch once again (to continue coding) using the following command:
    git checkout dev/yourreponame/bug/yourJIRAissuenumber
  6. Rebase your branch from the latest version of the master branch using the following command:
    git rebase mule-3.x
  7. Resolve any conflicts on your topic branch that may appear as a result of the changes to mule-3.x (i.e. master).
  8. Push the newly-rebased branch back to your fork on your git repository using the following command:
    git push origin dev/yourreponame/bug/yourJIRAissuenumber -f

E  Submitting a Pull Request

Ready to submit your patch for review and merging? Initiate a pull request in github!

  1. Review the MuleSoft Contributors' Agreement.
  2. From the repo of your branch, click the Pull Request button.
  3. 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 detailed instructions for submitting a pull request.)
  4. 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 master where appropriate.
  5. 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. 

 

Go Further

  • Rather than adjusting source code, you may wish to extend Mule by creating custom components. Refer to Extending for more details.
  • Beyond creating custom components, you can extend Mule even further using our Anypoint Connector DevKit.