To publish your app extension you need to save your changes to a remote branch and then to the master 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.
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. 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 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 save your changes to your local copy of the repo:
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.
In most cases, the top of your project’s Git repository is called the master, and 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’re ready to publish the work you’ve done in your private branch, you first Push your changes into the remote repository, thereby exposing your changes as a branch to everyone else in your project. (In Git terms, you do a Git Push operation to add it to the project’s Git repo; if a team member does a Git Pull operation at this point, they will get a copy of your branch as well.)
Once your changes are part of the project’s Git repo, your team members can clone the branch in their workspace 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 application extension, you might all be working off the same branch. For this reason, you should update the branch with your changes frequently using the Push command. Frequently pulling changes that other members make into your branch is also advised 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, the next step is to merge your changes to the source of truth, the master 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.
Publish the Application Extension
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 added from a branch to the main branch (often the master branch).
The easiest way to publish your changes is by opening the Publish Changes dialog box from the header in the Designer. 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 Changes. If you don't create a merge review request, the changes are merged immediately. If you create a merge review request, the changes can be merged after they've been reviewed and approved. Once the request is approved, you use the Merge action on the Merge Requests page to merge the changes.
Once you publish your changes, you can no longer use the Git branch that contained your changes, so you'll need to use a different branch if you want to make additional changes. 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.
When you're ready to merge your changes, you should publish the sandbox you used in your Oracle Cloud Application. 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. See Publishing Sandboxes: Procedure in Configuring and Extending Applications.
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.
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 when you use the Publish Changes action.
- Click Publish Changes in the Designer toolbar.
- Select the Merge Now tab and type a Commit Message.
- Click Publish Changes.
- Click Close.
Publish Changes that Require Review
If you are publishing changes and want to create a merge review request, you use the Merge After Review tab in the Publish Changes dialog box to enter the commit message and review details. If your project requires a review before changes can be merged, the Publish Changes will not have the Merge Now tab.
- Click Publish Changes in the Designer toolbar.
- Select the Merge After Review tab and type a Commit Message.
- Select the team members you want to review your changes.The members you select will be listed in the the Merge Review page as reviewers who can should review and can approve the merge request.
- Select the issues that you want to link to the merge review request.The issues you choose will be linked from the Merge Review page.
- Click Publish Changes.
When you click Publish Changes, the dialog box displays the Git commands that are automatically performed for you.
- Click Close.
Save Changes to the Git Repository with Git Commands
The most current version of an application extension's files are stored in a remote repository branch usually named "master". This branch is used to build the application extension. To get your changes into master, you first save the changes in the local branch in your workspace to a remote repository branch, and then merge that remote branch into the "master" branch.
When editing an application extension, you'll save all your changes to a local repository branch in your workspace first. Branches are usually created from the remote repository "master" branch, but might also be created from a different remote repository branch. Your workspace contains a local branch which is a copy (clone) of the remote branch. When editing your app extension, your changes are automatically saved in the local branch in your workspace and are not visible to others. To allow your team members to see your changes, you need to update the remote branch with the changes from your local branch.
After the remote branch is updated with your changes, a team member can view the changes by creating a clone of the remote branch in their workspace. They can also view the source code in the repository, including all branches, by opening Git in VB Studio.
If other team members are also working on the application extension, your local branch and the local branches in each of their workspaces might all be clones of the same remote branch. You should update the remote branch with your local changes frequently. This can help you to avoid accidentally making changes to files that someone else is also editing, which might result in a code conflict when adding your changes to the remote branch.
How Do I Save My Changes?
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.
When you make changes in your workspace, a badge is applied to the branch name in the header to let you know that the changes in your local branch haven't been saved to the remote branch.
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, they are not included 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.
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.
You can 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.
For details on resolving merge conflicts when merging a review branch, see Resolove a Merge Conflict in Managing Your Development Process with Visual Builder Studio.
Commit and Push Your Changes
All the changes you make in the Designer are stored in the local branch in your workspace and are invisible to your team members until you commit and push them to a remote branch.
Your must explicitly commit your changes before you can push them to the remote branch. You are prompted to commit and push the changes in your local branch if you try to switch to a new branch in your workspace or choose to Share your changes.
To commit changes in your local branch:
- Click the branch name in the toolbar and select Commit in the menu.
- Enter a commit message to describe the changes you are committing. Click Create Commit.
- Click the branch name in the toolbar and select Push in the menu.
- Enter a commit message to describe the changes you are pushing to the remote branch. Click Push to Git.
When your changes are pushed to the remote branch, the Push Content to Git Repository displays a message that says your files were successfully added.
You can see the changes that were added to the remote branch in the Recent Activities panel on the Project Home page. Pushing your changes adds all the files that you've committed since your previous push to the remote branch. The commit message for each commit included in the push is listed in the Recent Activities panel.
Create a Merge Request
After your changes have been pushed to the remote branch, you can create a merge request asking project members to review the changes before they are merged to another branch or the master repository branch.
A merge request might be required to merge changes from a branch to the master branch in your project. In the 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 create and work with merge requests, see Review Source Code with Merge Requests in Managing Your Development Process with Visual Builder Studio.
To create a merge request:
- Click Merge Requests in the main menu to open the Merge Request page.
- Click Create Merge Request.
- In the New Merge Request dialog box, select the Git repository for the application extension, the target branch and the review branch. Click Next.
For the target branch, you should select the master repository branch for the project if you are doing the final merge to the repository. For the review branch you should select the branch containing the changes you want reviewed.
You can merge a review branch into a branch that isn't master, but you should be careful when doing this, and its best to do this only when the review branch is a branch of the target branch.
- In the Details set of the wizard, select the project members that you want to review the changes. Click Next.It is good practice to also provide as many additional details as you can about your request, such as if the changes resolve an issue, and provide a summary of the changes.
- In the Description step of the wizard, add any additional details in the Edit Description field. Click Create.
Merge Changes From a Branch
When you've finished making changes on your branch and your changes have been approved, you use the Merge Request tool to merge your changes to the target branch you chose in your merge request, which can be another branch or master.
To merge a branch, you use the Merge command in a merge request that you created or one where you were assigned as a reviewer. The target branch and the branch that will be merged are already defined in the merge request.
It's good practice to ask some project members to review the 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 Managing Your Development Process with Visual Builder Studio.
To merge a branch:
- Click Merge Requests in the main menu and open your merge request.
- On the right side of the page, click Merge.
- In the Merge dialog box, type a description of the merge and click Create a Merge Commit.
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.
In the main Merge Requests window, you can open the table's Merged tab to confirm that your review branch was merged to the target branch.
After merging a branch to master, 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.
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:
- Click Enviroments in the main menu to open your project's Environments page.
- Select the development environment for your app extension.
App extension projects usually only have one development environment that the extensions are deployed to.
- Open the Deployments tab of your environment and click Application Extensions.
- 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.
If you think your app extension should have been deployed but you can't find it in the list, you should 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.