One of the great things about SuiteCRM is that it’s open source. This means that, if you find a bug, not only can you fix it but you can also share that fix with the world. This post will briefly cover how to go about contributing a SuiteCRM fix back into the project.
If you’ve found a bug in SuiteCRM the first thing you’ll want to do is to file an issue on the SuiteCRM Issues on GitHub remember to include any relevant information such as how to reproduce the issue and the expected/actual results.
If you have programming experience you may want to dive in and attempt to fix the problem. let’s follow a concrete example. I recently found a bug in SuiteCRM - setting the `records_per_page` property of a subpanel to a value greater than ten didn’t respect the value and also broke the pagination of the subpanel.
The first step was to create an issue on github: Issue 834 which explains the issue I was seeing.
Now we can go about tracking it down and possibly fixing it. If you haven’t already you’ll need to fork the SuiteCRM repository on GitHub:
This will create a copy of the SuiteCRM repository on our account that we can the push changes to.
We now want to clone our copy of the SuiteCRM repo. Here I’m using the terminal but feel free to use whatever tools you want.
#Clone our repo
git clone https://github.com/<YourUsername>/SuiteCRM.git
#Switch to the hotfix branch
git checkout hotfix
#Create a new Branch for our issue
git checkout -b Issue834
Creating a new branch specifically for our issue will insure we keep the hotfix branch clean in case we wish to fix future issues (Note that, as SuiteCRM changes you’ll need to keep your fork up to date, see details of that here Syncing a fork but we can ignore that for now).
After digging through the subpanel code the offending line in `data/SugarBean.php`
$limit = $sugar_config['list_max_entries_per_subpanel'];
gets replaced with
$limit = $max_per_page;
A nice easy fix. After making sure we test thoroughly it’s ready to be committed and pushed up to our fork.
#Add the file we've changed
git add data/SugarBean.php
#Add a descriptive commit method
git commit -m"Fall back to the $max_per_page value. These two values differing would cause broken pagination. Closes #834."
#Push up our changes and track our branch
git push --set-upstream origin Issue834
Note that the above uses the phrase “Closes #834”. This lets GitHub know that this commit will fix Issue 834 and it will automatically do that when our commit makes it into the master branch. This helps the SuiteCRM team keep track of issues too.
We now have our fix up on our fork. Now we want to create a pull request back to the project. Before doing this however we’ll need to sign the contributor agreement. How this is done will likely change in the future so please check the README on the SuiteCRM Repository for details.
With the contributor agreement signed we can put in our pull request.
After pressing the Pull Request button we’ll get the Pull Request page. Here we’ll want to create our pull request. The base fork should be the salesagility/SuiteCRM on the hotfix branch. The head fork will be our fork and whatever branch we created in the previous steps, in our case Issue834.
The text area should be a description of the work done, in our case the changes needed to fix #834.
Before finally hitting the big green “Create Pull Request” button we’ll want to take one last look at the changes on the bottom of the page. These should only be the changes necessary to fix the issue. Other fixes or changes should be in their own Pull Request. Once all this is done we can create the Pull Request.
Once created we’ll see a page with the details for the PR and we can bask in the warm fuzzy glow of knowing we’ve helped out the SuiteCRM project.
The SuiteCRM team will then hopefully merge in our fix ready for the next release of SuiteCRM or offer suggestions for changes.
Any questions or issues? Get in touch and let me know.