Power Platform ALM with the Development Hub - part 4 - Development Hub usage

Mini-series

This article is part of a mini-series about the Development Hub.
Part 1 - Introduction
Part 2 - Environment Setup
Part 3 - Configuring Development Hub
Part 4 - Development Hub usage (this article)

Welcome to an extensive exploration of Power Platform ALM using Development Hub. This guide aims to provide you with a comprehensive understanding of the functionality and utility of Development Hub in managing application lifecycle within Power Platform.

Setting the Stage: Issue Creation

The first step in your journey with Development Hub begins with creating an Issue record. This record is crucial when you are about to commence work on a new feature or fix a pre-existing bug.

Consider the following steps to create an Issue:

1. Navigate to the Issues sub-area under the main Issues area.
2. Choose 'New'.
3. Fill out the necessary fields as depicted in the table below:

1. Hit 'Save'.

Now, you've successfully created an Issue record!

Developing Solutions: Unmanaged Development Solution

To develop a solution for the Issue we created, we need an unmanaged development solution. The unmanaged solution will carry the name of the Issue.

Follow these steps to create an unmanaged solution:

1. Click the 'Develop' button in the command ribbon, this will trigger the creation of the unmanaged solution and set the status of the Issue to 'In Progress'.

2. Open the Power Platform Maker Portal and select the environment where Development Hub is installed. If you need to change the environment, select the Environment dropdown in the top right corner of the portal.

3. Choose 'Solutions' from the navigation panel on the left side of the portal. This will display all the solutions installed into the environment. You will see a solution with a display name that matches the name given to the issue you created earlier.

4. Now, you can add new and existing artifacts to your solution and make the necessary changes to resolve the Issue.

Case Study: Adding a New Table

Let's take an example to illustrate how you can add a new table to your solution.

1. To add a new table, select the + New button in the toolbar and choose Table from the dropdown list.

2. This action opens a pane on the right side of the portal where you can define the properties of the new table.

3. Once the table is created, you will see a list of the standard Dataverse columns. Now, you are ready to add further customizations to the table.

Steps to Follow Before Requesting a Merge

Before you request a merge, consider following these steps:

Run any potentially impacted tests locally against the development environment. This step helps in early identification of any issues that may have been introduced, making it an optimal time to find and resolve issues.

If you are making code changes, raising a draft pull request so team members can give feedback is useful. This way, your code review takes place outside of the solution merge process. If the code review happens during the merge process and issues are found, this will block other solution merges until your PR is approved.

Creating a Solution Merge

To incorporate your changes into the master solution and deploy them into the other environments, you need to create a Solution Merge.

Follow these steps to create a Solution Merge:

1. Open the Development Hub app, navigate to the Issue, and select the Development tab. You will see a view called Solution Merges. Click + New Solution Merge.

2. The Quick Create: Solution Merge pane will be displayed on the right side of the portal.

3. You will now see a record in the Solution Merges view for the merge record you created.

4. Select the record and click Edit or double click the row to open the Solution Merge form. You can now copy the URL and send it to someone to review and Approve.

Reviewing Solution Merges

To initiate the process of merging the developed changes into the master solution, the Solution Merge record must be approved. You can request another team member to review your solution merge. When reviewing a merge, look out for the following:

• Check if the solution contains everything it needs for a successful merge. For instance, Dependencies, Plugin Steps etc.
• Ensure that the solution does not contain items that it does not need. For example, when adding an existing Table to your solution, did all the components unexpectedly get included?

To approve a Solution Merge:

1. Open the solution merge form and click Approve in the toolbar. This will change the Status Reason from Awaiting Review to Approved.

• If there are no solution merges in progress, then the status reason will change to Merging. If another merge is in progress, it will be set to Queued. Queued solution merges will start as soon as the merges ahead of it have been complete.
• If the solution merge fails for any reason, the Status Reason will be set to Failed. Details of the error will be added to the Timeline.
• Once a solution has been merged into master, it is extracted into a branch with the same name as the Issue and a Pull Request is raised in Azure Devops with a link to the Work Item ID that was set on the Issue. The Status Reason of the solution merge is set to Awaiting PR Merge.

Manual Merge: A Deeper Dive

In some cases, the solution merge process needs to be paused to allow either the solution merge creator or approver to modify the target solution before it is extracted. This is useful for scenarios where the complete set of changes for a given issue couldn't be moved in an unmanaged solution.

An apt example of such a change would be deleting a component since there is no mechanism within an unmanaged solution to delete a component in the target environment.

When the merging process is in a state where manual merge activities can begin, the solution merge will transition to an Awaiting Manual Merge Activities status and a Flow Approval is created for either the solution merge creator or approver to action.

To resume the merging process after the manual activities are complete, follow these steps:

1. Navigate to the Power Automate Maker Portal (e.g. https://make.powerautomate.com/)
2. Ensure you are in the correct environment (top right)
3. Select Action Items on the left then Approvals
4. Select the created request in the list of "Received" requests
5. Select Merged as the response then Confirm to the bottom
6. The merge will now resume by extracting the target solution from the master environment.

Error Mitigation: Failed Merges

Not every merge will be successful and hence, understanding how to mitigate these is valuable. This section will cover what Development Hub does to handle these and the steps required to retry the merge.

Merging your development solution from dev to master could fail for a few reasons, the most common ones being missing solution dependencies and solution import timeout.

In case of a failure, the solution merge will transition into a Failed status and a note will be added to the timeline. If the development solution failed to import, the note will include import error resembling this note:

Otherwise, if any other error occurs, a more generic note is created which includes a link to the Cloud Flow run which you can use to diagnose the fault.

Once you believe the error to be resolved, you can retry the solution merge using the retry button found in the ribbon of the solution merge.

Please note that once the solution has begun merge, it blocks all other solution merges until it is complete, including while it is Failed. This is because once the development solution is imported in the master environment, the environment is considered "dirty" until the changes are merged into source control.

Reviewing the Pull Request

The customizations have now been extracted into the Git repository and a Pull Request has been created ready for review. To view the PR, open the Azure Devops project, expand the Repos section of the navigation on the left of the portal and select Pull requests.

The Overview tab contains the details of a PR such as required checks that must be completed before a PR can be completed, a list of required and optional reviewers and and comments that have been made.

Select the Files tab to view all of the files that have been changed as part of this PR. This is where you can make comments against lines of code which the owner of the PR will be notified about.

Approving the Pull Request

To approve a PR, follow these steps:

1. After checking the changes, approve the PR using the Approve button at the top right of the page.

2. Once all of the required checks have been successful, complete the PR using the Approve button.

2. This will open up a Complete pull request dialog where you can select merge type and post-completion options. You do not need to change any of the default settings. Selecting Complete merge will merge the PR branch into the Master branch and start the process of releasing the changes to the CI environment.

The Merge Process: An Overview

When a Solution Merge has been approved in Development Hub, a Power Automate Flow called When a solution merge is approved - > Merge the solution is triggered which executes a series of tasks to create a Pull Request in ADO.

The Issue Solution in the Development Hub environment is exported as an unmanaged solution and imported into the Master Environment. The contents of the Issue Solution are then merged into the Target Solution which is then Extracted from the Master Environment.

Extracting the Solution into a Feature Branch

The extraction of the Target Solution is carried out by a pipeline in Azure Devops (ADO) which in the following example is called almlab.

1. Login to the ADO project that contains your Repository and Pipelines.
2. Navigate to the Pipelines tab and select the sub-item also named Pipelines where you will see a list of recently run pipelines and the extract pipeline may still be running.

3. Clicking on the almlab pipeline opens up a new view which displays the run history in start time order.

4. Clicking on a run will open up its details, where you will see a Jobs section on the Summary tab.

5. Clicking on the Job will show you the steps it contains and the result. This is useful when troubleshooting pipeline failures to complete successfully as you can find the task that failed and once selected you will see debug information in the right-hand panel.

At this point, the change will either be committed directly to the master branch if the source control strategy for the repository is Push or create a new pull request if the strategy is Pull Request.

Validating the Feature Branch

Once the Extract pipeline (almlab) has successfully completed, the pipeline to build the solution is triggered.

This will build the solution to confirm it compiles with no issues and then run the Power Platform Solution Checker to run a static analysis of the solution against a set of best practice rules and quickly identify any problematic patterns found.

1. Navigate to the Pipelines tab and select the sub-item also named Pipelines where you will see a list of recently run pipelines. The build pipeline (ALMLAB - Package Build) will be listed.
2. Clicking on the ALMLAB - Package Build pipeline opens the run history for the pipeline in start time order.
3. Clicking on a run will open up the details. You will see a section with 2 tabs Stages and Jobs. You will see the Build stage which confirms the solution builds successfully and a Solution Checker stage which runs static code analysis against the solution components.
4. Clicking on a stage will open up the Job details where you can see the breakdown of tasks for the stages.

Approving the Pull Request

Once the PR has been approved the Feature branch will be merged into the Master branch of the source code.

The ALMLAB - Package Build pipeline with be run against the Master branch to confirm that the solution builds and the Solution Checker will analyze the solution components.

1. Navigate to the Pipelines tab and select the sub-item also named Pipelines where you will see a list of recently run pipelines. The build pipeline (ALMLAB - Package Build) will be listed.
2. Clicking on the ALMLAB - Package Build pipeline opens the run history for the pipeline in start time order.
3. Clicking on a run will open up the details. You will see a section with 2 tabs Stages and Jobs. You will see the Build stage which confirms the solution builds successfully and a Solution Checker stage which runs static code analysis against the solution components.
4. Clicking on a stage will open up the Job details where you can see the breakdown of tasks for the stages.

Releasing to the CI Environment

The solution contained in the Master branch is now deployed into the CI Environment. This is done using a Release pipeline in ADO.

1. Navigate to the Pipelines tab and select the sub-item Releases. The examples show a release called ALMLAB Release on the left panel where you can search for pipelines if required.
2. Select the release ALMLAB Release and you will see a tab on the right-hand side with a tab called releases which contains a list of the runs in order of start time.
3. Clicking a release run will display the Stages which the release runs. In this case, you will see 1 stage which deploys the solution into the CI Environment.
4. If you select a Stage you will be given the option to view logs. This will show you a list of steps contained in the stage. Selecting a step will display the tasks with the log information.

Congratulations! You have successfully navigated through the complex but rewarding journey of Power Platform ALM with Development Hub. Now, you're fully equipped to create, merge, and deploy solutions effectively. Happy developing!