After you have untangled your application and set up your package directories and initial package version, it’s time to work on a strategy for managing your package versions and active development projects in your source control systems. Having a good and practical Git strategy will be crucial for your Continuous Integration and Continuous Deployment workflows. This blog post covers how to create such a strategy.<\/p>\n
An intro to Git branching<\/h2>\n
Source control (and with that, Git) has been around for a long time in the Salesforce world. But for those who haven’t worked with Git and the Salesforce Platform yet, let’s look at briefly at a widely adapted Git branching strategy.<\/p>\n
\n\t\t\t \n\t\t\t (Photo source<\/a>)<\/p>\n In a nutshell:<\/p>\n While that itself sounds simple, it can get a bit complicated, especially when you have multiple branches running at the same time (which is not uncommon in software development, especially when you work in a team).<\/p>\n Here’s a small real-world example from a code race<\/i> that I did some years ago.<\/p>\n \n\t\t\t \n\t\t\t Blue is Building upon that branching strategy and your own company’s requirements, you may have (or should) extend the model. Before you start designing your Git strategy you should have answers to the following questions:<\/p>\n You may answer some or all of those questions with \u201cI want that on every commit.\u201d But then you’ll experience the delay that it takes to create a new package version before it can be installed. Waiting eight minutes before you get feedback if everything is okay from your CI system can feel like a long time, even more if you commit multiple times a day. Last but not least, there are daily limits for scratch org creation and package version creation request, so you don’t want to have an overly aggressive package version strategy, as it will clutter your environment and eat up your available resources.<\/p>\n What if you want to test package version creation and installation \u201conly\u201d on every Pull Request? On what branches? Develop<\/i>, master<\/i>, all feature<\/i> branches? There are many options. You want to find out if something is broken or may be broken as early as possible in your development workflow. However, you also don’t want to get slowed down by the process.<\/p>\n For our Easy Spaces app<\/a> we defined the following naming conventions for our Git branches:<\/p>\n For our sample application, we settled with what are standard names for Git branches, like develop<\/i> or master<\/i>. You should use names that make most sense to you and your organization. For example, packaging<\/i> could be partial-sandbox<\/i> and develop<\/i> could be full-sandbox<\/i>. There’s no limit in how you can customize. Just keep in mind that it needs to be manageable.<\/p>\n We also defined pre-conditions that should be met before a branch gets merged or code gets committed as well as which specific tasks should run. Here’s an excerpt, based on the used CircleCI workflow<\/a> (note that this graphic doesn’t include branch filtering yet):<\/p>\n \n\t\t\t \n\t\t\t Some of these decisions can and will be different for your organization. For example, you may want to run package creation also at a feature level if you want to make sure that your development team (or yourself) doesn’t introduce unpackageable features. For us, we decided that developers consult the documentation around supported Metadata types<\/a> before they start working on things. Relevant metadata which is yet not packageable should be moved into separate folders, like we did with the branding images for Salesforce Branding & Theming<\/a> in the Easy Spaces sample app<\/a>.<\/p>\n Let’s have a more detailed look at the why and how we made the aforementioned decisions for branches and their tasks.<\/p>\n If you think: \u201cHey, I can just remove the dependencies in the Once we’re done with the feature we’re also modifying the package version creation command in the CI configuration<\/a> with data like the version number, description and so on. This step is important because when we move the code via a PR into the ancestral You can see this branch as the intermediary between active development and preparation for first sandbox testing. In your organization you may make the decision to skip this branch and instead let someone manually create the package version. That’s totally legit. Choose what works best for you.<\/p>\n We’ve chosen our approach because it allows us to see all involved steps and their output within the UI of the chosen CI solution. For this we’re executing a script<\/a> that can be used via CI and can be also manually invoked from the developers workstation.<\/p>\n It’s noteworthy that we focus on installation of the packages. For that, we fetch all to be used versions for the packages via a bash script and deploy them. That way the sandbox gets hit with the latest code across all folders specified as package directories in the At this point some decisions need to be made. You have to define which package version is the one that you want to promote to production using the What’s always recommended is that you make use of tags on the master branch when you release a new version. That way you have your source of truth aligned with what is in production. Plus, you can go back anytime to see \u2014 and compare \u2014 changes between your custom application releases.<\/p>\n You remember the code race image? Here’s another one with multiple simultaneous branches going on. You want to make sure that always the correct one becomes the master.<\/p>\n \n\t\t\t \n\t\t\t Depending on your organizational requirements your Git branching strategy may be very similar or different to our approach. With the currently available capabilities of unlocked packages, not everything may work right away in that approach. It can even be different depending on the type of application or the level of modularization that you want or can introduce with unlocked packages.<\/p>\n What is most important is that you start thinking about a meaningful branching strategy \u2014 the sooner the better, as it will simplify your daily application development workflows. This not only applies to just unlocked packages but development in general.<\/p>\n If you need a refresh on Git, checkout the Git and Github Basics<\/a> module on Trailhead. Take a look at the Easy Spaces sample app<\/a>, which focuses on the modularization with unlocked packages. Finally, start experimenting with different Git branch strategies to find the perfect fit for your organization.<\/p>\n Ren\u00e9 Winkelmeyer works as Principal Developer Evangelist at Salesforce. He focuses on enterprise integrations, mobile, and security with the Lightning Platform. You can follow him on Twitter @muenzpraeger<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":" This is the fourth installment in a series exploring how to begin working with your apps in modular pieces, incorporating packages into your app development lifecycle, and what packaging may mean for your team\u2019s change management and release processes. Over the course of this series, we\u2019ll talk about: Part 1: What even is a package, […]<\/p>\n","protected":false},"author":3071,"featured_media":189260,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[2766],"tags":[2568],"coauthors":[],"class_list":["post-189254","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-tutorials","tag-packaging-unlocked"],"podcast_audio":{"audio_url":"","duration":""},"featured_image":"https:\/\/d259t2jj6zp7qm.cloudfront.net\/images\/v1530034177-trailhead_module_git_and_github_basics_f1rqxy.png?w=200","related_posts":[],"unstyled_content":" This is the fourth installment in a series exploring how to begin working with your apps in modular pieces, incorporating packages into your app development lifecycle, and what packaging may mean for your team\u2019s change management and release processes. Over the course of this series, we\u2019ll talk about:<\/p>\n After you have untangled your application and set up your package directories and initial package version, it’s time to work on a strategy for managing your package versions and active development projects in your source control systems. Having a good and practical Git strategy will be crucial for your Continuous Integration and Continuous Deployment workflows. This blog post covers how to create such a strategy.<\/p>\n Source control (and with that, Git) has been around for a long time in the Salesforce world. But for those who haven’t worked with Git and the Salesforce Platform yet, let’s look at briefly at a widely adapted Git branching strategy.<\/p>\n \n\t\t\t \n\t\t\t (Photo source<\/a>)<\/p>\n In a nutshell:<\/p>\n While that itself sounds simple, it can get a bit complicated, especially when you have multiple branches running at the same time (which is not uncommon in software development, especially when you work in a team).<\/p>\n Here’s a small real-world example from a code race<\/i> that I did some years ago.<\/p>\n \n\t\t\t \n\t\t\t Blue is Building upon that branching strategy and your own company’s requirements, you may have (or should) extend the model. Before you start designing your Git strategy you should have answers to the following questions:<\/p>\n You may answer some or all of those questions with \u201cI want that on every commit.\u201d But then you’ll experience the delay that it takes to create a new package version before it can be installed. Waiting eight minutes before you get feedback if everything is okay from your CI system can feel like a long time, even more if you commit multiple times a day. Last but not least, there are daily limits for scratch org creation and package version creation request, so you don’t want to have an overly aggressive package version strategy, as it will clutter your environment and eat up your available resources.<\/p>\n What if you want to test package version creation and installation \u201conly\u201d on every Pull Request? On what branches? Develop<\/i>, master<\/i>, all feature<\/i> branches? There are many options. You want to find out if something is broken or may be broken as early as possible in your development workflow. However, you also don’t want to get slowed down by the process.<\/p>\n For our Easy Spaces app<\/a> we defined the following naming conventions for our Git branches:<\/p>\n For our sample application, we settled with what are standard names for Git branches, like develop<\/i> or master<\/i>. You should use names that make most sense to you and your organization. For example, packaging<\/i> could be partial-sandbox<\/i> and develop<\/i> could be full-sandbox<\/i>. There’s no limit in how you can customize. Just keep in mind that it needs to be manageable.<\/p>\n We also defined pre-conditions that should be met before a branch gets merged or code gets committed as well as which specific tasks should run. Here’s an excerpt, based on the used CircleCI workflow<\/a> (note that this graphic doesn’t include branch filtering yet):<\/p>\n \n\t\t\t \n\t\t\t Some of these decisions can and will be different for your organization. For example, you may want to run package creation also at a feature level if you want to make sure that your development team (or yourself) doesn’t introduce unpackageable features. For us, we decided that developers consult the documentation around supported Metadata types<\/a> before they start working on things. Relevant metadata which is yet not packageable should be moved into separate folders, like we did with the branding images for Salesforce Branding & Theming<\/a> in the Easy Spaces sample app<\/a>.<\/p>\n Let’s have a more detailed look at the why and how we made the aforementioned decisions for branches and their tasks.<\/p>\n If you think: \u201cHey, I can just remove the dependencies in the Once we’re done with the feature we’re also modifying the package version creation command in the CI configuration<\/a> with data like the version number, description and so on. This step is important because when we move the code via a PR into the ancestral You can see this branch as the intermediary between active development and preparation for first sandbox testing. In your organization you may make the decision to skip this branch and instead let someone manually create the package version. That’s totally legit. Choose what works best for you.<\/p>\n![\"\"](\"https:\/\/d259t2jj6zp7qm.cloudfront.net\/images\/c_scale%2Cw_900-git_model_bjoajz.png\")
\n\t\t\t <\/span>\n\t\t\t<\/p>\n\n
development<\/code> branch.<\/li>\nfeature<\/code> or hotfix<\/code> branches. Those branches inherit from development<\/code>.<\/li>\ndevelopment<\/code> branch.<\/li>\ndevelopment<\/code> into master<\/code>. As versioning is important, the master<\/code> branch gets tagged with a version number.<\/li>\n<\/ul>\n![\"\"](\"https:\/\/d259t2jj6zp7qm.cloudfront.net\/images\/v1530033869-git-run_kj0s8a.png\")
\n\t\t\t <\/span>\n\t\t\t<\/p>\nmaster<\/code>, green is develop<\/code>, the other are feature<\/code> and hotfix<\/code> branches.<\/p>\nGit branching strategy<\/h2>\n
\n
\n
feature\/<\/code>package-name\/*<\/i><\/code> – a feature (and bug fix) branch for an individual package<\/li>\npackaging\/package-name\/*<\/i><\/code> – a per package branch that tests package creation and installation for an individual package<\/li>\npackaging<\/code> – this branch reflects the code change for partial sandbox or UAT sandbox<\/li>\ndevelop<\/code> – this branch reflects pre-production, for example a full-copy sandbox<\/li>\nmaster<\/code> – this branch is what reflects production<\/li>\n<\/ul>\n![\"\"](\"https:\/\/d259t2jj6zp7qm.cloudfront.net\/images\/c_scale%2Cw_900-workflow_haclgc.png\")
\n\t\t\t <\/span>\n\t\t\t<\/p>\nfeature\/package-name\/*<\/i><\/code> branches – after every commit<\/p>\n\n
packaging\/package-name\/*<\/i><\/code> branches – on every pull request coming in from a feature\/package-name<\/i><\/code> branch<\/p>\n\n
sfdx-project.json<\/code>) to sandbox org. All package directories will be deployed as packages.<\/li>\npackaging<\/code> branch – on every pull request coming in from a packaging\/package-name<\/i><\/code> branch<\/p>\n\n
sfdx-project.json<\/code>) to sandbox org. All package directories will be deployed as packages.<\/li>\ndevelop<\/code> branch – on every pull request coming in from the packaging<\/code> branch<\/p>\n\n
sfdx-project.json<\/code>) to full-copy sandbox. All package directories will be deployed as packages.<\/li>\nmaster<\/code> branch<\/p>\n\n
Branches and tasks in detail<\/h2>\n
feature\/package-name\/*<\/i><\/code> branches
\nFor these branches we decided to push all source using sfdx force:source:push <\/code>and wouldn’t use any packages. This decision is based on the following reasons:<\/p>\n\n
sfdx force:source:push<\/code> on the es-base-objects<\/i> folder and then install es-base-code<\/i> via package installation. This will fail because the es-base-code<\/i> package has the dependency of an installed es-base-objects<\/i> package.<\/li>\n<\/ul>\nsfdx-project.json<\/code>, and then do a push\/install package mix…\u201d – that won’t work. The dependencies are part of the created package version, so any manipulation in the sfdx-project.json<\/code> won’t have an effect. Been there, done that.<\/p>\npackaging\/package-name<\/i>\/<\/code> branch, the package version creation process kicks off.<\/p>\npackaging\/package-name\/*<\/i><\/code> branches
\nAfter a feature is completely developed, we move it to its packaging<\/code> branch. This is also where the focus goes from \u201ca feature works\u201d to \u201ca feature works AND gets packaged\u201d.<\/p>\npackaging<\/code> branch
\nOnce we know that the new feature works (thanks to testing) and that we have a new package, we want to install it in a sandbox. That can be a partial sandbox or a UAT sandbox for example. We’ve settled for our use case to name the branch \u201cpackaging,\u201d but you can (and should!) use a name that reflects your stage in the process, i.e. \u201cuat-sandbox\u201d.<\/p>\nsfdx-project.json<\/code> configuration.<\/p>\ndevelop<\/code> branch
\nThe develop<\/i> branch reflects what could be for you a full-copy sandbox. The steps are the same as in the packaging<\/i> branch with the focus on package installation. The steps don’t change. We only move to the next stage of testing environment before we move to production.<\/p>\nmaster<\/code> branch
\nNow, if you remember, there’s still the master<\/i> branch \u2014 with no actions. There’s also still the outstanding task of bringing the new package version(s) to production. This is the stage where we leave the path of continuous deployment and do some manual steps.<\/p>\nsfdx force:package:version:promote<\/code> command. You may want to say \u201cthe latest,\u201d but as development doesn’t stop in the world of continuous development, there maybe already the next version in testing in the packaging branch, depending on your strategy. So you have to manually pick a version and that’s what we recommend for now. Make a manual and educated decision because that will affect production and with that 5 or 5,000 users. After the promotion and installation of the package, submit the code to the master<\/code> branch.<\/p>\n![\"\"](\"https:\/\/d259t2jj6zp7qm.cloudfront.net\/images\/v1530034010-git-art_bppx8a.png\")
\n\t\t\t <\/span>\n\t\t\t<\/p>\nYour next steps<\/h2>\n
About the author<\/h2>\n
\n
An intro to Git branching<\/h2>\n
\n\t\t\t <\/span>\n\t\t\t<\/p>\n\n
development<\/code> branch.<\/li>\nfeature<\/code> or hotfix<\/code> branches. Those branches inherit from development<\/code>.<\/li>\ndevelopment<\/code> branch.<\/li>\ndevelopment<\/code> into master<\/code>. As versioning is important, the master<\/code> branch gets tagged with a version number.<\/li>\n<\/ul>\n\n\t\t\t <\/span>\n\t\t\t<\/p>\nmaster<\/code>, green is develop<\/code>, the other are feature<\/code> and hotfix<\/code> branches.<\/p>\nGit branching strategy<\/h2>\n
\n
\n
feature\/<\/code>package-name\/*<\/i><\/code> – a feature (and bug fix) branch for an individual package<\/li>\npackaging\/package-name\/*<\/i><\/code> – a per package branch that tests package creation and installation for an individual package<\/li>\npackaging<\/code> – this branch reflects the code change for partial sandbox or UAT sandbox<\/li>\ndevelop<\/code> – this branch reflects pre-production, for example a full-copy sandbox<\/li>\nmaster<\/code> – this branch is what reflects production<\/li>\n<\/ul>\n\n\t\t\t <\/span>\n\t\t\t<\/p>\nfeature\/package-name\/*<\/i><\/code> branches – after every commit<\/p>\n\n
packaging\/package-name\/*<\/i><\/code> branches – on every pull request coming in from a feature\/package-name<\/i><\/code> branch<\/p>\n\n
sfdx-project.json<\/code>) to sandbox org. All package directories will be deployed as packages.<\/li>\npackaging<\/code> branch – on every pull request coming in from a packaging\/package-name<\/i><\/code> branch<\/p>\n\n
sfdx-project.json<\/code>) to sandbox org. All package directories will be deployed as packages.<\/li>\ndevelop<\/code> branch – on every pull request coming in from the packaging<\/code> branch<\/p>\n\n
sfdx-project.json<\/code>) to full-copy sandbox. All package directories will be deployed as packages.<\/li>\nmaster<\/code> branch<\/p>\n\n
Branches and tasks in detail<\/h2>\n
feature\/package-name\/*<\/i><\/code> branches
\nFor these branches we decided to push all source using sfdx force:source:push <\/code>and wouldn’t use any packages. This decision is based on the following reasons:<\/p>\n\n
sfdx force:source:push<\/code> on the es-base-objects<\/i> folder and then install es-base-code<\/i> via package installation. This will fail because the es-base-code<\/i> package has the dependency of an installed es-base-objects<\/i> package.<\/li>\n<\/ul>\nsfdx-project.json<\/code>, and then do a push\/install package mix…\u201d – that won’t work. The dependencies are part of the created package version, so any manipulation in the sfdx-project.json<\/code> won’t have an effect. Been there, done that.<\/p>\npackaging\/package-name<\/i>\/<\/code> branch, the package version creation process kicks off.<\/p>\npackaging\/package-name\/*<\/i><\/code> branches
\nAfter a feature is completely developed, we move it to its packaging<\/code> branch. This is also where the focus goes from \u201ca feature works\u201d to \u201ca feature works AND gets packaged\u201d.<\/p>\n