Use Case: Volunteers for Salesforce
Some Salesforce managed packages provide developers in the community the opportunity to contribute with code and features. Packages such as the Non Profit Starter Pack or Volunteers for Salesforce are open source software, which means developers can contribute to the code on GitHub (https://github.com/) resulting into new features or improvements to the software. These features are then packaged into the managed version being upgraded.
University of New Hampshire engaged Daizy Logik to develop several enhancements to Volunteers for Salesforce that were then incorporated back into the package. Based on this work we developed this step-by-step technical guide on how to successfully contribute to an open source Salesforce managed package. The process described here uses Volunteers for Salesforce as an example but could be more generally applied to any open source managed package.
Development Environment Setup
To facilitate the setup of your development environment we recommend using these freely available utilities that should be available on both Mac and PC.
Step 1. GitHub and Git CLI Tool
To get started you’ll need a GitHub (https://github.com/) account and a Git CLI (command line interface) client. Use the instructions found at this link to get the Git client set up locally on your computer: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git.
Step 2. Ant and Force.com Migration Tool
In this guide we will use the Force.com Migration Tool (FMT) to set up the code in our development environment so you’ll want to download and install both the Ant utility (https://ant.apache.org/bindownload.cgi) and the Force.com Migration Tool (https://developer.salesforce.com/docs/atlas.en-us.daas.meta/daas/forcemigrationtool_install.htm). Follow the installation instructions for both utilities.
Getting the Code
Next, you will need to get the actual open source code you’ll be modifying. You will be making all your code changes on what is essentially a copy of the source code, not affecting the original until you’re absolutely sure your changes are tested and ready for prime time.
Step 3. Your New Code Repository
In this step you will create a new repository for Volunteers for Salesforce and clone the entire source code to your machine.
Log in to your GitHub account and search for the Volunteers for Salesforce repository. Once you find it click the Fork button. This will create a new Volunteers for Salesforce remote repository in your GitHub account. This is where you will check-in your changes without affecting the actual package.
Next, open a command line terminal on your machine. Navigate to the parent folder where you want your code to reside and type this command:
git clone https://github.com/your-git-account/Volunteers-for-Salesforce.git V4SGIT
This command will download the Volunteers for Salesforce app files to the V4SGIT folder. (Note that you can use any folder name you would like instead of V4SGIT.)
After this step, you should see all the V4S app files in your folder.
Make sure you enabled your machine to display system/hidden files. You should see a “.git” folder, and “.gitattributes” and “.gitignore” files, in your local folder.
Prepping the Development Box
You will be working with an “unmanaged” version of the code, which means you will have to take some extra steps in order to get that code into your development environment.
Step 4. Create a new Salesforce Developer instance
Go to developer.salesforce.com and create a new free developer instance. This is the instance where you will be doing your development and making your changes. You will need to upload the Volunteers for Salesforce unmanaged code in this instance and make sure this copy of the code does not have the namespace prefix.
Once the instance is up and running, add language support. In addition to English, add Spanish and French language support.
Step 5. Upload the Volunteers for Salesforce Code and Metadata to your new instance
Create a new folder FMT (force.com migration tool) where you will keep your scripts. You can of course use any folder name you’d like.
Create two subfolders under FMT: adhoc and retrieveAdHoc.
Create a new text file called build.properties under FMT.
Add the following content to the file:
sf.target.username = your-dev-instance-user-name sf.target.password = your-password followed by your-security-token sf.pkgName = package.xml sf.target.serverurl = https://login.salesforce.com
Save the file.
Under FMT, create a new xml file called build.xml. Add the following content:
<project name="V4S Deployment" basedir="." xmlns:sf="antlib:com.salesforce">
<property file="build.properties"/>
<property environment="env"/>
<target name="deployAdHoc" description="Deploys the contents of the retrieveAdHoc directory to target box">
<sf:deploy username="${sf.target.username}" password="${sf.target.password}" serverurl="${sf.target.serverurl}"
deployRoot="retrieveAdHoc" maxPoll="1000" pollWaitMillis="10000"/>
</target>
</project>
Copy the entire content of the V4SGIT/src to the FMT/deployAdHoc folder.
Under FMT/deployAdHoc edit the package.xml file and remove this line:
<namespacePrefix>GW_Volunteers</namespacePrefix>
Save the package.xml file.
Open a command line window and navigate to your FMT folder and type this command:
ant deployAdHoc
This command will upload the unmanaged Volunteers for Salesforce code to your developer instance.
Step 6. Setup a local working folder for your code
You could use the V4SGIT folder, you’ve set up earlier as a working folder, but we chose to keep its contents unchanged just in case we needed to revert some change along the way.
You can use your favorite IDE (we used Eclipse in this case) and set up a new Force.com project to connect to your new dev instance. As a local folder we used a new V4SAPP folder, in the same parent folder as V4SGIT.
Step 7. Point the V4SAPP to your remote Git repository
Remember you cloned your code to the V4SGIT folder by running this command back in Step 3:
git clone https://github.com/your-git-account/Volunteers-for-Salesforce.git V4SGIT
Now all we have to do is copy the .git folder, the .gitattributes and the .gitignore files from the V4SGIT folder to the V4SAPP folder.
Step 8. Test the setup
We want to make sure that changes made in this new development environment can be ultimately pushed back to the point of origin, GitHub.
To verify this, open Eclipse, and open a Visualforce page, for example VolunteersJobListingFS. Add a comment at the top of the page. Save the file to server. Make sure your changes are updated on the server.
In order to push your file to the Git remote repository open the command line window. Go to your V4SAPP folder and type this command:
git add VolunteersJobListingFS
This gets your file ready to be checked-in.
Then type this command:
git commit –m “test commit”
Now your changes are committed locally and ready to be uploaded to GitHub.
Type this command:
git push origin master
Go to your GitHub remote repository and verify that your comment shows up in the file you changed.
If all is well and your changes are showing up in GitHub, you are ready to start working.
Back to the Community and GitHub
Any changes you make to an open source app such as Volunteers for Salesforce will need to be vetted and approved by the owner of the package, before they get officially merged into the managed package.
Step 9. Making your changes available to the community
After you have made your changes, it’s time to make them available to the users of the application by pushing them back into the managed package. You will need to go to your remote repository for Volunteers for Salesforce and create a pull request. This will inform the package owner that your changes are complete. The owner will inspect your changes, and if everything looks good, he or she will merge your changes into the application.
What Else Do I Need to Know?
When you choose to contribute to an open source Salesforce managed package your changes will need to be vetted by the package owner before they can be merged back into the main code branch. It is a good idea to run the requirements of the changes by the owner before you start development so you can get them pre-approved. That does not guarantee that the code changes will be automatically accepted, but at least you’ll know the package owner agrees that these features are valuable to the community.
The package owner will comment on the pull request and might ask you to make additional changes before they approve the merge. We recommend that each pull request have all the changes pertinent to a specific feature or fix. Don’t mix multiple different features and fixes into one pull request, because that will make it much harder on the reviewer, and if they end up rejecting the pull request due to a specific item none of your changes will go in.
DaizyLogik 