Let the platform do the work
SugarClubContact+1 (877) 842-7276

Development Methodology

Overview

This page discusses standard practices that we recommend for improving the success rates of Sugar development projects. 

Development Best Practices

When developing Sugar® customizations as part of an on-site CRM project implementation, we recommended placing the entire Sugar application filesystem under source code management. Sugar developers know that customizations made to Sugar are placed under the ./custom/ directory. But during the lifecycle of a CRM implementation, you will need to upgrade Sugar versions, which will change core files. Many projects will also need to track other related project files that may not all be Sugar platform code. For example, pre-flight SQL scripts, data migration scripts, Web server configuration settings, etc.

For SugarCloud projects and ISVs, if you are building a custom module package or integration designed to be installed into many Sugar instances (including SugarCloud instances), then tracking only ./custom/ directory files should be enough.

Using .gitignore Files

Today, many developers choose to use Git as their source control management. There are certain Sugar application files that you do not want to track; most of these are generated files that are created at runtime or are Sugar instance-specific configuration files.

Below is a sample .gitignore file that you can use or adapt to the source control management system of your choice.

  *.log
/.htaccess
/config.php
/config_override.php
/cache
/upgrades/module
/upload
/custom/blowfish
/custom/history
/custom/application/Ext
/custom/modules/*/Ext
/custom/Extension/**/*orderMapping.php

Recommendations for Development Teams

Code quality is important to maintain because Sugar customizations run in the same environment as the rest of the Sugar application. Here are a few best practices to help development teams uphold code quality.

  • Adopt an appropriate Git workflow for development. For reference, see Atlassian's tutorial on Git workflow options.
  • Develop within feature branches that are tested before being merged back into master to keep master stable.
  • Avoid workflows that involve developers committing directly into the master branch to prevent code destabilization.
  • Development teams should always perform code reviews before merging in new code.

Deploying Sugar Code

Where you plan to deploy Sugar code is the biggest factor in determining how Sugar code should be deployed and how your project should be managed.

Are you working on a Sugar project for an on-premise Sugar implementation? Are you working on a custom module that you plan on distributing through SugarExchange? Are you planning a solely REST API integration? The answers to these questions guide how you should develop and deploy Sugar code.

  • Sugar on-site projects : Develop these customizations using the exact version and flavor of Sugar that you plan to use in production.
  • SugarCloud projects : Develop these customizations on the latest available version of Sugar for the particular flavor the customer has purchased.
  • Custom modules or integrations : If you plan on distributing your customization to many Sugar customers via SugarExchange or channel partners, design your customization with Sugar's cloud service in mind.
    • Sugar's cloud service is more restrictive than our on-site installs regarding supported customizations.
    • A customization designed for Sugar's cloud service can be supported in Sugar on-site instances, but the inverse is not always true.

For more information on Sugar's cloud service restrictions, please refer to the SugarCloud Policy Guide.

Packaging

The packaging of customizations is not a concern for many Sugar projects. Many projects just use Git (or some other file version control) to manage the distribution and deployment of Sugar code customizations. However, there are situations where the packaging of Sugar customizations is necessary.

If you plan on distributing Sugar custom code, then you must package your customization as a Module Loadable Package (a .zip file that includes all custom code along with a manifest file). It is easy to write a script to build a module loadable package either from custom directory content or by extracting customizations out of a development environment. See examples on Github here and here.

Note: Sugar Sell Essentials customers do not have the ability to upload custom file packages to Sugar using Module Loader.

In some Enterprise environments, changes are tightly controlled, and ownership of various Sugar application components may be spread across multiple teams, requiring a coordinated deployment. For example, a Database Administrator (DBA) may be responsible for implementing database schema (DDL) changes and a System Administrator may be responsible for implementing file system changes.

For these situations:

File system changes can be accounted for using Git to determine the difference between current production state and the latest changes to be deployed.

DDL changes can be accounted for via deploying latest file system changes on a clone of Sugar production instance and running Quick Repair command. Sugar will prompt you with any DDL changes that need to be made that you can then capture and share with your DBA.

Data Manipulation Language (DML) changes, if necessary, should be managed within SQL or PHP scripts.

Deployment

If using the traditional Git-based deployment, then deploying new Sugar code is as easy as checking out the latest branch and then running Quick Repair and Rebuild. Run the quick repair from the Sugar user interface, or script it for fully automated deployment.

When deploying to an instance on Sugar's cloud service, it is necessary to install the package manually using Module Loader. It is not possible to automate the deployment of packages into instances on Sugar's cloud service.

In a coordinated deployment, database changes should be deployed first, followed by filesystem changes, followed by a Quick Repair (if permitted) to clear system caches. You can clear caches manually by deleting the contents of the ./cache/ directory and then truncate the metadata_cache table in the Sugar database. The Sugar application regenerates these caches as needed.

Using Sugar Studio to deploy changes into new environments (especially Production) is not recommended. Manually re-creating customizations using the Studio user interface can be error-prone. It also runs the risk of inadvertently overwriting other code customizations. It may be initially slower to create a custom field, etc. manually using extensions on filesystem but, in the long run, you benefit from better change management and automation.

Managing Multiple Environments

CRMs are business-critical applications so development should never be performed directly on your production environment. A typical Sugar project involves multiple staging environments as well as individual development environments that each Sugar developer uses for actual coding.

SugarCRM recommends 4 different environments:

  • Production environment : used by real users
  • User Acceptance Test (UAT) environment : used by business stakeholders to sign off on changes that go into production
  • Quality Assurance environment : used for test and validation of new features and bug fixes
  • Development environments : used by individual Sugar developers to create and test code (often running on a local laptop or PC)

Code changes that flow upstream from a development environment should not be allowed into production without going through quality assurance (QA) and user acceptance testing (UAT) first. The intermediate environments serve as gates between development and production that help intercept problems before they reach production.

User and CRM data that needs to flow downstream from production environment should pass through intermediate environments as well to ensure consistency and that it is cleaned or anonymized of any personally identifiable or sensitive information.

Consistency

Maintaining as much consistency as possible for each of these environments is essential. Inconsistent environments can create issues where bugs are reproducible in one environment and not others (for example, a bug that only appears in production). Many times, these bugs are traced to configuration parameters that are not directly related to Sugar or the features and customizations under development.

To replicate your production environment as accurately as possible, we recommend you use VM or container technology in your development and QA environments.

Your UAT environment should match the infrastructure of your production environment.

SugarCRM uses a variety of container technologies in developing the core Sugar application and for working on Sugar projects. In particular, we use Virtual Box, VMWare, Amazon AMIs, Docker containers, Vagrant, and Packer. SugarCRM Engineering also uses Puppet to centrally manage the provisioning and configuration of all these different environments.

Testing

SugarCRM recommends using a variety of testing methods to ensure the quality of your Sugar project. Perform unit testing, functional testing (either manual or GUI automation), system integration testing, user acceptance testing, and performance testing.

  • Unit testing should be applied to ensure that even the smallest code units within your application are behaving as expected.
  • Functional testing should be performed to ensure that each feature and function behaves the way it was designed.
  • System Integration testing should be performed to ensure that Sugar co-exists with external systems and that data flows between all these systems successfully.
  • User acceptance testing should be performed by key stakeholders to ensure that your project is meeting business requirements.
  • Performance testing should be performed to ensure that the Sugar application's responsiveness meets user expectations and that the application continues to scale.

In our experience, neglecting any of these tests can negatively impact a Sugar project in terms of maintainability, customer satisfaction, and business success. 

In the next section, we introduce some tools and open-source resources that can help you start a QA practice for your project.

Sugar Test Tools

For Sugar customers and partners, SugarCRM provides Test Tools that can be used to verify and perform quality assurance on Sugar customizations. Use of Sugar test technology requires familiarity with PHPUnit for PHP unit testing, Jasmine for JavaScript unit testing, and Apache JMeter for performance load testing.

Sugar Unit Tests

The Sugar Unit Test suites are the automated unit tests developed and maintained by SugarCRM Engineering during the process of building and releasing each new Sugar release. As part of our development process, these tests are required to run "green" (100% passing) at all times on each master release branch. Essentially, these tests form a regression test suite for an uncustomized version of Sugar running in our controlled build environment.

With that understanding, here is a recommended approach to take advantage of these unit tests.

  • Run test suite against an uncustomized copy of Sugar in your development environment to establish a baseline. Not all tests may immediately pass; some may fail due to configuration differences between your development environment and SugarCRM Engineering's controlled build environment.
  • Correct any observed failures or skip/remove the failing tests to create a base test suite that is 100% passing.
  • As you develop customizations on Sugar, ensure that your base test suite continues to pass.
  • Create new tests for new code customizations that you create.

Sugar Performance Tests

Instead of sanitizing data from a production environment for purposes of load testing, SugarCRM provides an open source tool called Tidbit that can be used to generate pseudo-random data to populate a Sugar instance with representable data.

We also provide Apache JMeter scenarios to Sugar customers and partners who request access. These JMeter scenarios can be used to drive a simulated load against the Sugar REST API interface used by Sugar. They can validate that your customizations have not had an unexpected impact on the performance of a Sugar instance.

DevOps

In order to facilitate and streamline development processes, Sugar recommends implementing DevOps automation. Use a tool such as Jenkins to orchestrate test automation, stage changes in any environment (dev, QA, UAT, and prod) for manual verification, and manage the promotion of changes from one environment to the next.

  • Perform automated tests (e.g. unit tests) on each commit.
  • Stage development changes on at least a nightly basis for use by QA or demos.
  • Automate the rollback of changes in any environment as needed.
  • Automate notifications to affected and responsible parties whenever a test fails, or a build fails to deploy.

Co-Existing with Studio Customizations

Sugar Studio and Module Builder enable administrator users to implement quick changes to a Sugar environment. But Sugar Studio lacks the rigorous change control that larger CRM projects need. Sometimes, Studio changes can even break code-level Sugar customizations. For this reason, we often discourage using Studio on heavily customized Sugar instances.

However, if Sugar Studio is an important up-front requirement for a CRM project, then there are strategies you can adopt for your customizations to avoid conflicts.

Sugar Studio can be used to modify the layouts, fields, and relationships for the majority of modules in Sugar. Module Builder can be used to define new modules along with their layouts, fields, and relationships. In practice, this means that the fields and layouts for any module's record view, list view, mobile view, and subpanels can be customized using simple administration tools.

Studio users, therefore, could potentially break code customizations that are reliant on a particular field or having a field on a particular layout or location. Here are some practices to avoid conflicts between Studio customizations and custom code:

  • Avoid custom record, list, and subpanel view controllers because Studio users can change fields and layouts that affect expectations within your controller code.
  • Avoid custom record validations because Studio users can change fields and layouts that affect expectations within your validation code.
  • Avoid hard-coded integrations that rely on a particular field because Studio users can change fields that affect expectations within your integration.
  • Avoid new field and relationship vardefs customizations because Studio users can create new fields and relationships.
  • Avoid viewdefs customizations for record, list, and subpanel layouts because Studio users perform these customizations.

Many customizations have a smaller risk of side effects related to Studio customizations. Here is a list of some changes that administrator users cannot perform via Studio:

  • Adding custom dashlets
  • Adding custom layouts or additions to footer or header
  • Adding custom actions in record view action dropdown
  • Adding metadata-aware integrations that discover fields and modules on the system
  • Adding logic hooks

Conversely, certain customizations can provide Studio users with additional tools:

  • Adding custom Sugar Logic functions
  • Adding custom Sugar field types