7 Publish the Application Extension

To publish your app extension, you first save your local changes to a remote branch, then merge that branch into the main branch. You can do all these steps at one time using the Publish action, or you can use Git commands in your workspace to do them individually.

Review the Process

If you’re unfamiliar with Git commands, it may be helpful to review the relationship between your workspace, your project, and the Oracle Cloud Applications development environment.

• In most cases, the trunk or main branch of your project’s Git repository is the source from which your artifacts (like an app extension) are built. Your project’s Git repository is also called the remote repository, while the clone in your workspace is called the local repository.

• When you create a workspace (or one is created for you), you get a clone of the project’s Git repository and all its branches. Branches are usually created from the main branch, but might also be created from a different branch. Your workspace will contain a branch (which might be new or might already exist), but no one else can see the changes you make to the branch in your workspace until you choose to make them visible. This local branch is where you work on your application extension.

• As you make your changes, you frequently use the Commit action from the Designer’s drop-down menu to mark the changes in your local repository branch that you want to copy to the remote repository:

  
  
  
  Description of the illustration designer-commit.png
  
  

• You can also add a commit message describing the reason you updated those files (for example, "Added new layout X for field Y"). These commit messages can help you later to identify which files were changed and why.

• You use the Push action from the Designer’s drop-down menu to copy changes in your branch in the local repository to the branch in the remote repository. All the changes that you've committed since your previous push are copied to the branch in the remote repository.

• Once your changes are pushed to the remote branch they are available to everyone else in your project. Your team members can clone the branch in their workspaces and view the changes. They can also view the source code in the repository, including all branches, by opening Git in VB Studio.

• If other team members are working on the same application extension you are, you might all be working off the same branch. For this reason, you should update the remote branch with your changes frequently using the Commit and Push commands.

• You use the Pull action to update your local branch with any changes that other members push into the remote branch. It's a good idea to do this frequently to ensure that the branch in your workspace has the most recent changes. This can help you to avoid accidentally making changes to files that someone else is editing or has edited, which can result in a code conflict that you would then need to resolve.

• When you’re completely done with your work and you've pushed all your changes into the remote branch, the next step is to merge the changes in the remote branch into the source of truth, the main branch. You might be required to submit a merge request before the merge is permitted. A merge request describes the reason and scope of the changes to be merged, and often requires some team members to explicitly approve the request after they have reviewed the changes.

• You can use Publish in the Designer's header when you’re ready to publish the work you’ve done in the private branch in your local repository. The Publish action commits any uncommitted changes, pushes the changes into the remote branch, and then either merges the branch into the main branch or creates a merge request.

Publish the Application Extension

The easiest way to publish your changes is by opening the Publish Changes dialog box from the header in the Designer. The Publish operation combines Git operations (commit, push, merge) to merge the changes in your local repository branch into the main branch. In the dialog box you simply enter a commit message describing the changes (and add reviewers and issue if you're also creating a merge review request) and click Publish. If you don't create a merge review request, the changes are merged immediately.

Description of the illustration designer-publish-changes-action.png

Depending on how your project is configured, you might be able to publish your changes without creating a merge review request, but it's good practice to ask your team members to review the changes you made before you publish it. A code review is usually required before changes are merged from a branch into the main branch.

If you create a merge review request, the changes in the branch can be merged into main branch after they've been reviewed and approved in the Merge Requests page in VB Studio. For the steps to do this, see Merge Remote Branches.

Note:

Don't use the Publish action if you aren't ready to merge the remote branch into main branch. You can't use a remote branch after it's been merged into the main branch.

When you're ready to merge your changes, publish the sandbox you used in your Oracle Cloud Application, if you used one. Publishing the sandbox before merging your application extension changes to the main repository can help avoid potential problems resulting from using two different data models. For more about using and publishing sandboxes, see Sandboxes in Configuring and Extending Applications.

Note:

When you change your data model in App Composer, you need to publish those changes before you can use them in your app extension. For example, if you create some custom fields in App Composer, an app extension published to a test environment can use the new custom fields after the new data model is published to the test environment. When you publish your app extension to a different environment, for example, your production environment, you'll also need to use App Composer to publish the new data model to the production environment.

Once you merge a branch into the main branch, you can no longer use it (or your local copy of it). A new branch is created automatically for you when you publish your changes, and you can use it to make additional changes or you can create your own branch.

Your project is probably set up so that each time changes are merged into the master branch, the application extension artifacts are built from the repository and automatically deployed to the Oracle Cloud Application's test environment for further tests.

Note:

To deploy your application extension, the pipeline's deployment job must be configured with the credentials of a user who has permissions to connect and deploy to the Oracle Cloud Application environment. (These must be Oracle Cloud Application credentials, as opposed to VB Studio or SSO credentials.) The privilege granting permission to deploy is FND_ADMINISTER_SANDBOX_PRIV. If your project owner hasn't provided this information, you'll be prompted to provide it each time you click Publish. If your credentials don't allow you to deploy to the Visual Builder instance, talk to your project owner or an administrator to get credentials that you can use. The credentials that you enter when prompted, if valid, will be permanently saved in the deployment job. Your administrator can also choose to enter the credentials directly in the build job, so you aren't prompted for them when you try to deploy your app. You won't be able to publish without these credentials. If your user credentials don't allow you to deploy to the environment, talk to your project owner or an administrator. See Configure the Deployment Job in Administering Visual Builder Studio for details on how an admin can add the missing credentials.

You'll see notifications like the following in your workspace about the status of your jobs, including when a job has started, when it has finished, and when one fails.

Description of the illustration notification-build.png

Publish Changes Without Creating a Review

If your project is configured to allow you to merge changes from your branch without creating a merge review request, you can use the Merge Now tab in the Publish Changes dialog box.

To publish your application extension without creating a merge review request:

1. Click Publish in the Designer toolbar.
2. Select the Merge Now tab and type a commit message.
   
   

   
   Description of the illustration designer-publish-changes.png

   
   
3. Click Publish Changes.
4. Click Close.

Publish Changes that Require Review

If you don't see the Merge Now option in the Publish Changes dialog, that means that a merge request is required before you can merge your changes. If you see both tabs, that means the option to create a merge request is yours. If your project requires a review before changes can be merged, the Publish Changes dialog will not have the Merge Now tab.

When you create a merge request you can specify which team members you want to review the changes. The requirements of the merge request will depend on how your project is set up, for example, a certain member might be required to approve the request before the changes can be merged. For details on how to work with merge requests, see Review Source Code with Merge Requests in Using Visual Builder Studio.

To create a merge request in the Publish Changes dialog box:

1. Click Publish in the Designer toolbar.
2. Select the Merge After Review tab and type a commit message.
   
   

   
   Description of the illustration designer-publish-changes-aftermerge.png

   
   
3. Select the team members you want to review your changes.
   The members you select will be listed in the Merge Requests page as reviewers. A reviewer can approve or reject a merge request, but it is not required. You can merge the changes even if they have not been reviewed or approved.
4. Select the VB Studio issues that you want to link to the merge review request, assuming that your project is using them.
5. Click Publish Changes.

   When you click Publish Changes, the dialog box displays the Git commands that are automatically performed for you.

   
   

   
   Description of the illustration designer-publish-changes-merge.png

   
   
6. Click Close.

After the reviewers have reviewed and approved the changes, go to the Merge Requests page in VB Studio and use the Merge action to merge the changes into the main branch. For the steps to do this, see Merge Remote Branches.

Video: Overview of Your Git Repositories

This video illustrates the relationship between your workspace and the Git repository in your project.

How Do I Add My Changes to a Remote Branch?

After you edit files in your workspace you need to save them to a remote branch in order to share the changes in your app extension with your team members. Until you save those changes to a remote branch, they only exist in the local branch in your workspace, which means that only you can see them.

When you make changes in your workspace, an orange dot appears next to the branch name in the header to let you know that you have some uncommitted changes.

Description of the illustration designer-repo-badge.png

You can also open the Git panel in the Navigator to view all the changes in your workspace that haven't been committed.

Saving your changes to a remote branch is a two-step process: commit and push. The first step you must perform is a commit. When you make a commit, you are basically grouping the files in your local branch that you want to save to the remote branch, and providing a description of the group. This may seem redundant, but it helps document the process of saving files to the repository, which can be very helpful later if you need to track down which files were changed.

For example, if you make some changes to add a new layout to include a field, when you "commit" the changes you can add a commit message describing the reason you updated those files ("Added new layout X for field Y"). You then might change some other files to add a rule for the new layout, and add a commit message describing those changes ("Added rule Z for layout X"). When you eventually save these files to the repository, those commit messages can help you identify which files were changed and why. When you look at the list of changes made to the repository, you can easily see what files were changed and the reasons for changing them.

The second step is push, which saves all the files in the groups that you've "committed" to the remote branch, so a single "push" might save several groups of files. If you have edited some files but haven't committed them, you are prompted to commit them when you "push" your changes to the repository.

Files and artifacts can have the status Edited, Committed, or Pushed (the default status). The name of each file in the Navigator is color-coded to indicate its status.

To commit and push changes from your local branch to a remote branch:

1. Click the branch name in the toolbar and select Commit in the menu.
2. Enter a commit message to describe the changes you are committing. Click Commit.
   
   
   Description of the illustration designer-commit-create.png
   
   
3. Click the branch name in the toolbar and select Push in the menu.
4. Click Push Changes in the Push dialog box.

   The Push dialog box shows the names of the local branch with your changes and the remote branch where they'll be pushed to.

   
   
   
   Description of the illustration designer-commit-pushtorepo.png
   
   

   You'll see a message in the Push dialog box if any of your changes are still uncommitted when you attempt to push your changes. You can enter a commit message in the dialog box and click Commit All and Push.

   
   
   
   Description of the illustration designer-commit-pushwithcommit.png
   
   

   Pushing your changes adds all the files that you've committed since your previous push to the remote branch.

A notification is displayed in the Designer each time you commit and push changes.

You can see the changes that were added to the remote branch in the Recent Activities panel on the Project Home page. The panel lists the commit message for each commit included in a push to the remote branch.

Description of the illustration project-repo-recentactivity.png

After you push your changed files to the branch in the remote repository, you can merge the remote branch into another branch, or into the main branch.

To merge a remote branch into a branch that isn't the main branch, use the Merge Requests tool in VB Studio. For details on how to create and work with merge requests, see Review Source Code with Merge Requests in Using Visual Builder Studio.

Note:

You can use the Publish action in the Designer header if you want to commit, push changes to a remote branch and merge the remote branch into the main branch in one operation. Don't use the Publish action if you aren't ready to merge the remote branch into the main branch.

Merge Remote Branches

You use the Merge Requests tool in VB Studio to merge remote branches, for example, when you want to merge a remote branch with your changes into the main branch. Your team members can use the tool to review the changes you want to merge into the main branch, leave comments, and to approve or reject your merge request. If your request is rejected, you'll need to fix any problems and create a new merge request.

A merge request is created automatically when you use the Merge After Review option in the Publish Changes dialog box in the Designer. To publish the app extension, you'll need to open the Merge Requests page in VB Studio and merge the branch into the main branch.

You can also create merge requests in the Merge Requests page. You'll need to create a merge request when you want to merge two remote branches. For details on how to create and work with merge requests, see Review Source Code with Merge Requests in Using Visual Builder Studio.

It's good practice to ask some project members to review your changes, but it isn’t mandatory to get approval from all reviewers before you merge the review branch. Note that you can’t merge the review branch if the target branch is locked. If it's locked you need to contact the project owner to unlock the target branch. For details on how to merge branches, see Merge Branches and Close the Merge Request in Using Visual Builder Studio.

To merge two remote branches:

1. Open Merge Requests in the VB Studio left navigator and open the merge request.
2. On the right side of the page, click Merge.
   
   

   
   Description of the illustration merge-request-merge.png

   
   
3. In the Merge dialog box, type a description of the merge and click Create a Merge Commit.

   If changes in your sandbox are not yet published, it's recommended that you publish the sandbox before merging your application extension changes to avoid potential problems.

   To delete the review branch after the commits are merged with the target branch, you can select Delete Branch in the dialog box.

When your merge is complete you'll see a summary of the merge request in the Conversation tab. If you didn't select Delete Branch in the Merge dialog box, you can delete it now by clicking Delete Branch. After merging a branch to the main branch, the branch is automatically closed and you can no longer use it. To make additional changes you'll need to create a new branch in your workspace or open an existing branch.

In the main Merge Requests page, you can see the status of merge requests in the table, and locate requests using the built-in filters, for example, Created By Me.

Description of the illustration merge-request-merged.png

Keep Your Local and Remote Branches in Sync to Avoid Conflicts

If you and another team member are working together on an app extension, you will be using the same Git repository and might be working off the same branch and editing the same files. This can result in a code confict, where you and a team member make changes to the same line of code in a file.

To help minimize the number of conflicts, the best practice is to make sure your local branch and the remote branch are in sync and up to date. You do this by committing and pushing often. Each time you commit or push changes to the branch, Git will check the remote branch to see if there were any updates since the last time you checked, and update your local branch with the changes.

If a code conflict occurs, you'll have to resolve it before you can update the branch with your changes. VB Studio will let you know if there is a conflict when you try to commit or merge your changes, and you can use the conflict resolution editor to fix the problems in each file by selecting whose changes you want to keep. You can continue when all the conflicts are resolved.

For details on resolving merge conflicts when merging a review branch, see Resolove a Merge Conflict in Using Visual Builder Studio.

Description of the illustration designer-conflict-resolver.png

Use the Audits pane in the Designer to scan and locate places in your code that are flagged as errors because a conflict has not been resolved.

Description of the illustration designer-audit.png

View Your App Extension Deployments

After you've published your app extension, you can check your project's Environments tab to see if it's been deployed to your development environment.

To view the deployed app extensions for your base application:

1. Click Environments in the VB Studio left navigator to open your project's Environments page.
2. Select the development environment for your app extension.

   App extension projects usually only have one development environment that the extensions are deployed to.

3. Open the Deployments tab for your environment and click Application Extensions.
4. Expand the node for your base application to see a list of deployed app extensions.

   There might be several app extensions deployed to your base application, so you'll need to look for the extension id and name in the list of deployed extensions to confirm that yours has been deployed.

   
   

   
   Description of the illustration publish-env-deployments.png

   
   

If you think your app extension should have been deployed but you can't find it in the list, check the build jobs for your project to check if the job has finished, or contact your project administrator if you think there might be a problem with deploying the app extension.