ADE Getting Started

Oracle Corporation Confidential - For Oracle internal use only

Getting Started with the Advanced Development Environment (ADE) for Fusion Applications

Authors: Barbara Kostelec, Rahul Pandey

Creation Date: 16 April 2008

Last Updated: 4 June 2008

Document Version: 1.3

Oracle Corporation Confidential - For Oracle internal use only ii

Contributors

Name Role Content Contribution

Rahul Pandey Senior Development Manager, ADE Substantial content contribution throughout this document

Michael Rohan Development Manager, Server Technologies

Unified integration process

Sam Mahaney Principal Configuration Engineer, Server Technologies

Project transactions

Samy Sikdar Development Manager, Server Technologies

Merge request tool

Sunil Boddapati Software Development Manager, Server Technologies

Project transactions

Varma Bhupatiraju Server Farm Development Manager Server farms Cynthia Goh David Chan Dave Merrill Denis Goddard Ken Mizuta Manikandan Purushothaman Min Fang Shan Gao Toju George

Various Provided valuable input during document review

Change Record

Date Name Version Change Reference

16 April 2008 Barbara Kostelec 1.0 Created document.

30 April 2008 Barbara Kostelec 1.1 Made various updates in preparation for development review.

18 May 2008 Barbara Kostelec 1.2 Made various updates in response to review comments.

3 June 2008 Barbara Kostelec 1.3 Updated various sections based on meetings with multiple ST contacts and Rahul: Project transactions, Merge request tool, Unified Integration Process, Merge conflict resolution.

Oracle Corporation Confidential - For Oracle internal use only iii

Table of Contents Table of Contents ........................................................................................................................................... iii Introduction..................................................................................................................................................... 5

Purpose and scope................................................................................................................................................ 5 Assumptions.......................................................................................................................................................... 5 How this guide is organized ................................................................................................................................... 5 Document references ............................................................................................................................................ 5

ADE Overview................................................................................................................................................. 7 What is ADE? ........................................................................................................................................................ 7

Benefits......................................................................................................................................................................................................................7 Components ..............................................................................................................................................................................................................7

Where can I use ADE? .......................................................................................................................................... 8 New Linux boxes.......................................................................................................................................................................................................8 Hosted reservation system ......................................................................................................................................................................................8

Roles..................................................................................................................................................................... 8 Integrator ...................................................................................................................................................................................................................9 Developer ..................................................................................................................................................................................................................9

ADE Integrations .......................................................................................................................................... 10 JDeveloper (JDev)................................................................................................................................................10 CruiseControl .......................................................................................................................................................10 Unified Integration Process (UIP)..........................................................................................................................10 Farms...................................................................................................................................................................10 Merge request tool (mergereq)..............................................................................................................................10 Bug database .......................................................................................................................................................11

Terms and Concepts for Integrators and Developers ............................................................................... 12 Common terms.....................................................................................................................................................12 ADE development flow .........................................................................................................................................14 Development process models ...............................................................................................................................14

Label-Transaction Model........................................................................................................................................................................................14 Project Transactions...............................................................................................................................................................................................15

Shared transactions..............................................................................................................................................15 Additional Concepts for Integrators ........................................................................................................... 16

Labels and UIP.....................................................................................................................................................16 Project transactions (PT) ......................................................................................................................................16

Using ADE - for Developers ......................................................................................................................... 17 Commands...........................................................................................................................................................17

1. showseries ...................................................................................................................................................................................................17 2. showlabels....................................................................................................................................................................................................17 3. createview ....................................................................................................................................................................................................17 4. useview.........................................................................................................................................................................................................17 5. Start JDev.....................................................................................................................................................................................................18 6. begintrans.....................................................................................................................................................................................................18 7. co ..................................................................................................................................................................................................................18 8. Edit, build, and test ......................................................................................................................................................................................18 9. ci....................................................................................................................................................................................................................18 10. refreshview...................................................................................................................................................................................................18 11. beginmerge ..................................................................................................................................................................................................18 12. mergetrans ...................................................................................................................................................................................................19 13. Edit, build, and test ......................................................................................................................................................................................19 14. endmerge .....................................................................................................................................................................................................19

Merging ................................................................................................................................................................19 Sharing transactions .............................................................................................................................................19

sharetrans ...............................................................................................................................................................................................................19 sync..........................................................................................................................................................................................................................20 endsharetrans .........................................................................................................................................................................................................20

Oracle Corporation Confidential - For Oracle internal use only iv

Merging transactions across branches..................................................................................................................20 createview ...............................................................................................................................................................................................................20 useview....................................................................................................................................................................................................................20 begintrans................................................................................................................................................................................................................20

Additional commands ...........................................................................................................................................20 abortmerge ..............................................................................................................................................................................................................21 aborttrans ................................................................................................................................................................................................................21 cmhelp .....................................................................................................................................................................................................................21 desc .........................................................................................................................................................................................................................21 describetrans...........................................................................................................................................................................................................21 destroyview .............................................................................................................................................................................................................21 endtrans...................................................................................................................................................................................................................21 lsco...........................................................................................................................................................................................................................21 lstrans ......................................................................................................................................................................................................................21 lsviews .....................................................................................................................................................................................................................21 mkdir ........................................................................................................................................................................................................................22 mkelem ....................................................................................................................................................................................................................22 pwv...........................................................................................................................................................................................................................22 rm.............................................................................................................................................................................................................................22 savetrans .................................................................................................................................................................................................................22 unbranch..................................................................................................................................................................................................................22 unco .........................................................................................................................................................................................................................22 unmkelem................................................................................................................................................................................................................22

Using ADE - for Integrators......................................................................................................................... 23 Configuring UIP ....................................................................................................................................................23

Integration Commands ...........................................................................................................................................................................................23 Integration Tasks ....................................................................................................................................................................................................24 Integration Parameters...........................................................................................................................................................................................24

Creating a PT .......................................................................................................................................................24 create.......................................................................................................................................................................................................................24

Refreshing a PT branch from a label on its parent branch .....................................................................................24 beginrefresh ............................................................................................................................................................................................................24 useview....................................................................................................................................................................................................................25 endrefresh ...............................................................................................................................................................................................................25

Merging a PT branch to its parent branch .............................................................................................................25 beginmerge .............................................................................................................................................................................................................25 useview....................................................................................................................................................................................................................25 merge.......................................................................................................................................................................................................................25 endmerge ................................................................................................................................................................................................................25

Aborting a PT merge or refresh.............................................................................................................................26 abortrefresh .............................................................................................................................................................................................................26 abortmerge ..............................................................................................................................................................................................................26

Resolving PT merge or refresh conflicts................................................................................................................26 reassign ...................................................................................................................................................................................................................27

Using the merge request (mergereq) tool ..............................................................................................................27 Prerequisites and configuration .............................................................................................................................................................................27 Running mergereq..................................................................................................................................................................................................27

Getting Help .................................................................................................................................................. 29

Oracle Corporation Confidential - For Oracle internal use only 5

Introduction

Purpose and scope

Fusion Applications Development will use the Advanced Development Environment (ADE) for their development work. The purpose of this guide is to provide applications development with the basic information needed to start using ADE. The audience for this document includes application developers who will be using ADE in their daily work or who will be involved in managing certain ADE activities such as branching and labeling.

In addition to providing the basics of using ADE, this guide will also cover:

• How to use JDeveloper with ADE on your workstation.

• How to manage build and test cycles.

• How to uptake changes from other teams and manage dependencies.

This document will not cover topics such as how to administer your workstation.

Assumptions

This guide assumes:

• Your product successfully migrated to ADE.

• Your workstation is running a standard development image of an operating system that contains ADE.

• You have a YP master account. For additional information on required setup, see the Migrating to ADE document: https://kix.oraclecorp.com/KIX/display.php?labelId=2608&articleId=120821.

• You attended ADE training or reviewed the training materials.

How this guide is organized

This document begins with an overview of ADE. In addition to describing ADE components and configurations, the overview introduces the integrator and developer roles. Next is a section on the various tools and applications that integrate with ADE, followed by basic terms and concepts. ADE commands follow and the last section focuses on where and how to get help.

Document references

The following collateral served as input to this guide:

Title Location

Migrating to ADE

https://kix.oraclecorp.com/KIX/display.php?labelId=2608&articleId=120821

ADE for Fusion Apps

http://ade.us.oracle.com/twiki/bin/view/FusionApps/WebHome

ADE Command Reference

http://ade.us.oracle.com/twiki/bin/view/ADEFAQ/AdeCommandReference

ADE Home http://ade.us.oracle.com

ADE Training

http://ade.us.oracle.com/twiki/pub/ADETEAM/TrainingSessions/ADETraining.ppt

ADE User’s PDF: http://ade.us.oracle.com/twiki/pub/ADE32/WebHome/ADE_UG_321.pdf


Guide 3.2

HTML: http://ade.us.oracle.com/docs/adeUG/

Merge Request User Guide

http://staav14.us.oracle.com:9999/twiki/bin/view/AIMEWEB/MRUserGuide

Project Transactions User’s Guide 1.0

http://staav14.us.oracle.com:9999/twiki/pub/INTEGTeam/ProjectTransactionsUserGuide/Project_Transactions.html

Unified Integration Process (UIP) Reference Information

http://aimeweb.us.oracle.com/intg-doc/reference/index.html

Unified Integration Process (UIP) Tutorial

http://aimeweb.us.oracle.com/intg-doc/handbook/tutorial.html


ADE Overview This section describes the benefits of using ADE, the components that comprise it, and the roles that use it.

What is ADE?

The Advanced Development Environment (ADE) is a software configuration management (SCM) system developed by the Server Technologies (ST) software engineering team. It’s an Oracle based client-server application that enables efficient and effective software development.

Benefits There are multiple benefits of using ADE for source control management:

• Based on a scalable, highly available, multi-node RAC architecture with a geographically isolated disaster recovery instance.

• Has a distributed architecture with no single point of failure.

• Provides an isolated environment for development work.

• Supports the development of multiple release codelines in parallel.

• Supports propagation of code changes from codeline to codeline.

• Includes built-in commands and utilities to make parallel development easier.

• Provides a dedicated support command for reporting problems.

• Delivers patches and upgrades automatically.

Components

ADE consists of four main components: a repository database, labels, views, and transactions. See Table 1 for descriptions of each component.

Table 1 - ADE Components

Component Description

Repository database Stores all source code along with related metadata.

File versions: Stored as Oracle BLOB in compressed XDELTA format.

Metadata: Includes information such as who modified the object, when it was modified, and why. Metadata is stored as native Oracle datatypes such as varchar2 and date.

Labels A snapshot of all files, directories, symbolic links, derived objects, test results, and dependencies

associated with a point in time in the development of a product. Includes the list of changes since the previous label. Created automatically and monitored by an integrator for build issues or if any configuration changes are required. Used from a local label server (NFS file system).

Views An individual workspace based on a label, where all source code related work is done.

Transactions Represents the main unit of work, also known as a change set. Associates a logically related set of changes such as a bug fix or feature into a single autonomous atomic unit. A view can have only one active transaction at any given time. Isolates one source code change from another.


Where can I use ADE?

In a typical configuration, the ADE client runs on a developer’s workstation. It uses SQL*Net to communicate with the database server when required. The database server is also known as the ADE repository. See Figure 1 for an example of a typical configuration.

Figure 1 - Workstation Configured with ADE

There are additional ways in which ADE is installed and enabled for use. Here's a complete list of supported configurations.

New Linux boxes This is the primary and preferred method for using ADE in your daily work. ADE is included in new Linux boxes.

Hosted reservation system If you don't have a Linux box, or if you need to perform database related work on an EMS environment, you can lease a box from the hosted reservation system for a limited period of time. In the future, you will be able to lease a box to obtain ADE on platforms other than Linux. See this page for additional information: http://stit-webbac.us.oracle.com/stit-hrs/HRShome.html.

Roles

The various types of activities required to support ADE for a given product can be categorized into two roles: Integrator and Developer. There are references to these roles throughout this guide. The ADE terms mentioned in the role descriptions are defined later in this guide.


Integrator

Each product and product family needs an integrator. In some cases, such as for smaller products, an individual may act as integrator for more than one product. An integrator could expect to spend approximately 15 to 20% of their time performing the following activities:

• Managing CruiseControl driven automated product labeling, code building, and Enterprise Archive (EAR) file deployment to a standalone OC4J instance.

• Managing labeling frequency and determining if labels should be propagated to the IDC label server.

• Managing product dependencies and uptake of new releases of JDeveloper.

• Managing product branches and determining product branching strategies.

• Refreshing and merging product and product family branches.

In addition, the integrator should know how different parts of the product integrate together at build and runtime.

Developer Individuals on a product development team who perform the following types of day to day activities:

• Coding product features

• Fixing bugs


ADE Integrations This section lists the various tools and applications that integrate with ADE. You’ll find more information on using these integrations later in this guide.

JDeveloper (JDev)

The ADE integration with JDeveloper is enabled through an ADE plug-in that is included in JDeveloper for Fusion Apps. This extension allows you to perform various ADE operations from within JDev. View this page for additional information on the plug-in: http://aseng-wiki.us.oracle.com/asengwiki/display/ASDevJDeveloper/JDevADEPlugin.

CruiseControl

Continuous Integration (CI) is a software development process. Its primary goal is to keep the codeline in a stable state at all times, while accepting developers’ changes as rapidly as possible. CruiseControl is a framework for a continuous build process. It includes, but is not limited to, plug-ins for email notification, Ant, and various source control tools. A web interface is provided to view details of the current and previous builds. The ADE/CruiseControl integration takes advantage of several aspects of the Server Technologies development environment. These allow snapshots to be created in parallel. As a result, transactions merged more than an hour apart are integrated and tested independently, so that problems can be pinpointed to a specific code change. See this page for more information: http://cruisecontrol.us.oracle.com.

Unified Integration Process (UIP)

In order to produce labels and run builds efficiently ADE makes use of UIP, a task-based framework used to define a sequence of ADE operations such as label, build, regress, promote, and publish. UIP is automatically enabled in an ADE environment. UIP is a set of wrappers over a number of lower-level configuration management operations with hooks into a computing grid known as the Integration Farm. See the ST Integration Handbook for more information on UIP: http://aimeweb.us.oracle.com/intg-doc/handbook/index.html.

Farms

Farms are computing grid resources for all developers. There are two types of farms:

• Integration Farm or iFarm: A dedicated computing grid for running integration jobs. This database driven interface is used for scheduling, running, and querying labeling jobs. See the Integration Farm Home page for more information: http://dlsun2355.us.oracle.com:7778/ifarm/ifarm.jsp.

• Test Farm: A dedicated computing grid for running developer code changes through regression tests.

Merge request tool (mergereq)

The merge request tool acts as a gating facility to keep the mainline stable by preventing undesired developer code changes from merging into the mainline. The tool is highly flexible and allows for customizable workflows. Depending on individual product team requirements, mergereq can perform various sanity tests on developer code changes. Mergereq can be configured to send mail to interested parties, check certain transactions types, and record the merge request in the mergereq database. These and other settings can be configured by Release Management and Development.


For more information on this tool, see the Mergereq User Guide: http://staav14.us.oracle.com:9999/twiki/bin/view/AIMEWEB/MRUserGuide.

Bug database

If a code change that is, a transaction, is based on a bug number, ADE automatically updates that bug when the fix is merged into a branch. The begin transaction (begintrans) command supports bug number entry. See the Using ADE – for Developers section for information on this command.


Terms and Concepts for Integrators and Developers Review the key terms in Table 2 and the concepts in the rest of this section before you begin using ADE.

Common terms Table 2 - Common ADE Terms

Term Description

Branch A method of organizing versions of objects to enable simultaneous development on different codelines of that same object and to provide code isolation.

ADE supports the following branches:

System System branches are visible to all developers and are part of a product’s code set. The following are system branches: Main

• A product’s main codeline. Release maintenance

• Created by integrators usually when a product is released so that major product enhancements can proceed on the main branch while bug fixes can be made on the release maintenance branch.

• May have one or more child branches such as a project transaction branch. Project transaction (PT)

• Created by integrators. • A sparse branch with all the characteristics and properties of a typical main branch. For example,

transactions can be created from and merged to project it, labels and snapshots can be created, and consumers can pick PT labels.

• May be set up to be created off a main or release maintenance branch. Private The following is a private branch: Developer transaction

• Automatically created by ADE. • A way to isolate development and/or bug fix work of one developer from that of another. • When a developer checks out a versioned object during a transaction, ADE creates a developer

transaction branch on the version of the object referenced by the view. All check ins and check outs occur against that developer transaction branch. Only when the developer merges the transaction will the changes to the versioned elements get merged from the latest version on the developer transaction branch into the latest version on the project transaction branch. The new file versions created on the parent system branch as a result of the merge are picked up by the next label.

Element An object under version control such as files, directories, and symbolic links. Also known as a versioned object. Each element has a unique object ID in ADE and may be referenced by the complete file system path from its top level directory to its leaf name (for example, fusionapps/prc/po/build.xml).

Label A type of metadata associated with element versions. An element can have any number of labels associated with any version, but any given label can be associated with only one version of a given element. A snapshot of a product. In this sense, a label consists of all elements in a product having a given label and label metadata associated with them. A label may optionally also include all of the elements of each dependent product and derived objects of the product and the dependent products.

Snapshot labels are automatically created by CruiseControl and are identified by the suffix ‘.S’ (for example, FUSIONAPPS_PT.PRCPONM4_LINUX_080430.1104.S).

Label format and components

• All alpha characters must be upper case.


• Numeric characters are allowed. • Non-alpha characters period (“.”) and hyphen (“-”) are allowed. • Labels have a four part format consisting of: PRODUCT, BRANCH, PLATFORM, and

DATE. Each part is delimited by the underscore (“_”) character. Following is a breakdown of the individual components comprising label: FUSIONAPPS_PT.PRCPOSM4_ LINUX_080322.1900

1. FUSIONAPPS: Represents the product. The component value is fixed for fusion

applications. 2. PT.PRCPOSM4: This part of the label name consists of the following two

components: � PT: Represents the branch. In this case, this is a project transaction branch.

This value cannot be updated. � PRCPOSM4: Represents the product family, product, and milestone. This is

the recommended naming convention to follow when defining label names. There is no validation against this part of the label when it’s created.

3. LINUX: Represents the platform. The value cannot be updated. 4. 080322.1900: Represents the date and time (Pacific Time) when the label was

created. The value cannot be updated.

Label series A set of labels that have the same PRODUCT, BRANCH (in the label sense), and PLATFORM. A label series corresponds to a product’s code base on a particular branch for a particular platform.

The series name format is <product>_<branch>_<platform> (for example, FUSIONAPPS_MAIN_LINUX).

Label server An NFS server that stores labeled versions of elements. Accessed from the ADE view. Not writable by developers. During transactions, ADE makes local writable copies of elements that developers check out in the transaction prior to changing.

Merge The process of merging changed elements from one branch to another, as in the following examples:

• Refreshing a development transaction branch with changes from a PT branch

• Merging developer transaction changes into a PT branch.

Refresh The process of pulling changes from the system branch and modifying the state of a view to make it consistent with some criteria, usually a label.

Transaction A unit of work done in isolation from other developers’ work.

Transactions are isolated on a transaction branch which, when complete, is merged back into the parent system branch to make it part of the product’s next label on that system branch.

May consist of changes to many elements that can be treated as a unit and either included or removed from a product with a single operation.

Transaction name should be all lower case.

View • A set of resources that presents a private workspace to a user. Resources include file system structures such as directories, symbolic links to a label server, and environment variable settings that enable ADE commands to work in the context of a shell process.

• Allows a user to see one and only one version of each element in the product and any dependent

product. Versions of elements are selected based on a configuration specification.

• Views typically also contain derived objects which can be referenced through symbolic links to a label server, copied, or built into local storage.


• Each user can have multiple views. Users in different views work with the same files but do not affect

each other until merging their work.

ADE development flow

Figure 2 illustrates how ADE fits into a typical development flow. In this example, a developer checks out file version 4 and begins to work in the developer transaction (private) branch. In the meantime, the file on the project transaction (system) branch is changed by another user. The file is now version 5. The two sets of changes must be reconciled. In this case, ADE forces the developer to refresh the view, that is, merge from the project transaction branch to the latest version on the developer’s transaction branch. Once this is done, the developer must test the transaction again to make sure there are no issues with the merged version. ADE will then allow the changes to be merged down to the project transaction branch.

Figure 2 - Sample Development Flow

Development process models

Fusion Apps Development will use the Label-Transaction model. Project transactions provide an additional layer of structure to this model.

Label-Transaction Model Labels are produced on a regular basis (typically once per day, but as frequently as every few hours, and infrequently as once every few weeks depending on the requirements of the development team). This model preserves each transaction as a separate unit of work and gives developers a consistent view of the product. Changes made by each transaction are independent of one another.


Each developer or development team works on a single feature or bug in a transaction on a label. When the work is complete and tested, the transaction is merged back to the system branch. Those changes then appear in the next label. Before beginning the merge transaction process, the developer must refresh the view forward to the latest label, that is, if another label has been produced while the transaction was open. This ensures that difficult merge issues can be dealt with on the developer's transaction (private) branch, not during the merge to the system branch. Once the changes are merged into the system branch, the transaction effectively disappears from the developer's view until the next label is produced, and the view is refreshed up to that label. Each label can be thought of as the previous label, plus a set of zero or more transactions, possibly hundreds or thousands of transactions. Part of the process of producing a label is building the product and running a complete set of tests. It becomes the task of integrators and testers to determine which transaction is the source of any new problem and, where possible, to roll the problem transaction out of the label so that other development work continues. Snapshot labels are produced on a cycle of a few hours instead of a day. Test results may or may not be available for each label; if they are, it is easier to determine which transaction introduced the problem. CruiseControl checks for newly merged transactions on an hourly basis and kicks off a new snapshot label. Because of timing constraints, each snapshot label may contain more than one transaction, but the number will be much less than it would be where the label is produced on a daily basis. In a rapidly changing environment, the result will be many labels, each with one or a relatively few transactions. If you need CruiseControl to check for newly merged transactions more or less frequently than the default hourly basis, file a request against the ADE team using the ade cmhelp command. The check can be configured at the label series level.

Project Transactions

Project transactions add a layer of structure to the Label-Transaction model. For example, a complex new piece of functionality requiring many weeks of work on the part of more than a small handful of developers, may be best treated as a project. In this model, Project Labels are produced for individual projects. Project labels are based on a particular label on the main codeline. Individual developers then create transactions based on these project labels. These individual transactions then merge to form the next project transaction label, which contains only the changes submitted by developers participating in the project. From time to time, the project may be refreshed to a more recent main label. Once the project is deemed complete, or at least stable enough to be put into the main codeline, the project itself is merged and so appears in the next main label.

Shared transactions

A shared transaction is a transaction used by several developers. Shared transactions are intended for larger collaborative efforts (two or more users), long-term efforts (days, weeks, or even months), or when these developers need to have their own isolated stable environment. Typically a transaction is shared because the developers are participating in the same development task, such as a bug fix or an enhancement. In a shared transaction, there is one (and only one) owning view, and one or more other views sharing the transaction.


Additional Concepts for Integrators

Labels and UIP

The UIP framework automates regular label production and is used to manage product dependencies. UIP sits on top of ADE. UIP functionality is primarily concerned with handling parameters and tasks. Parameter values relate to the integration being performed such as the label being integrated, while tasks represent the steps required to integrate the new label. The following links provide additional information on UIP: http://aimeweb.us.oracle.com/intg-doc/handbook/index.html http://aimeweb.us.oracle.com/intg-doc/handbook/tutorial.html

Project transactions (PT)

Project transactions are intended for larger collaborative efforts involving six or more users, or when developers’ changes need to be synchronized with other teams working on a larger shared codebase. Any number of project transactions may be developed concurrently. There are five basic phases in a PT lifecycle:

• Create the initial project label and branch.

• Create developer transactions on the project label.

• Create new project transaction integration labels, (automatically by CruiseControl).

• Refresh the project transaction to the new parent branch label.

• Merge project transaction to the parent branch.

Project Transactions are managed (created, refreshed, merged, and so on) through a series of scripts accessible via the farm project interface. Only products that are integrated in iFarm can create PT labels. The product must have all the necessary UIP tasks defined in its configuration definition files. Task names must conform to the iFarm naming conventions. For more information on project transactions, review the Project Transactions User’s Guide: http://staav14.us.oracle.com:9999/twiki/pub/INTEGTeam/ProjectTransactionsUserGuide/Project_Transactions.html


Using ADE - for Developers This section describes the basic ADE commands a developer would run when making code changes to an existing file. This basic scenario assumes the following:

• The integrator created the necessary label series and labels.

• The transaction is not shared.

• An internal set of build and test procedures have been established.

• The developer has logged into the workstation where ADE is installed.

If you encounter an error while running an ADE command, use ade cmhelp to automatically file a support request. You can find more information on this command here: http://ade.us.oracle.com/twiki/bin/view/ADEFAQ/GenAdeQ001#ade_cmhelp. For a comprehensive list of support resources, see the Getting Help section.

Commands

Commands are listed in the order in which they should be run. If JDev can also be used to execute the command, JDev navigation is provided. Usage examples do not include all available command arguments. See the ADE Command Reference page: http://ade.us.oracle.com/twiki/bin/view/ADEFAQ/AdeCommandReference or, to get the most current usage information, append the –help argument to the command.

1. showseries

If you are not given a label to use for your view, run the showseries command. This command lists the label series that are available for a given product, branch, and platform.

Usage: ade showseries -prod/uct <prod_name> Example: ade showseries –prod fusionapps

2. showlabels Once you identify the label series to use for your view, run the showlabels command to see the labels available for that series.

Usage: ade showlabels -series <seriesname> Example: ade showlabels –series FUSIONAPPS_PT.CRMTRIAL_LINUX

3. createview This command creates a workspace in which files can be viewed and edited. The same view can be used by many different windows or processes simultaneously. You must specify a label when running this command.

Usage: ade createview –label <label> <view name> Example: ade createview –label FUSIONAPPS_PT.CRMTRIAL_LINUX_080516.1601.S crmtrial_view

4. useview The useview command sets the context to the created view and opens a new shell. In addition, it changes the directory to the root directory for the label to which the view is refreshed and sets a number of environment variables. Variables that ADE sets directly are prefixed with “ADE_” (for example, ADE_VIEW_NAME).

Usage: ade useview <view name> Example: ade useview crmtrial


5. Start JDev

If you are working on your Linux workstation, invoke JDeveloper from the local installed location. Once started, choose ADE as the versioning system from the versioning menu. Always look in JDev’s message pane for important messages from ADE command execution.

6. begintrans Development work in ADE is grouped by transactions. Use this command to start a transaction. Use one transaction for each logical unit of work, enhancement, or bug fix. Usage: ade begintrans –bug <bugNum> or ade begintrans <txnName>} JDev navigation: Versioning > Begintrans

Recommendation: Once you are in a transaction and start to modify files, run the savetrans command before you leave for the day.

7. co The check out command makes the file writable for you. It also supports multi-line comments. Enter a period “(.)” followed by the return key to terminate comment entry. The comment entered here will be the default comment used by the checkin (ci) command.

Usage: ade co –c<”comment> <filename> JDev navigation: Either right click on the file and choose checkout from Versioning or Select a file and click checkout from the Versioning menu on the top menu bar.

8. Edit, build, and test

Perform this step as per your product’s development processes.

9. ci

The ci command will check in the versioned file or files. You can use the –all argument to check in all checked out files and directories.

Usage: ade ci <filename> JDev navigation: Either right click on the file and choose checkin from Versioning or Select a file and click checkin from the Versioning menu on the top menu bar.

10. refreshview This command updates the view to a new label so new changes are available to the current transaction. Review the Resolving PT merge or refresh conflicts section for additional information on conflict resolution.

Usage: ade refreshview –latest JDev navigation: Versioning > Refreshview If you see the following message upon running refreshview, exit from JDev, exit from the view, then re-enter the view via the ade useview <view name> command. =============================================================================== ade WARNING: ENVIRONMENT VARIABLE SETUP HAS CHANGED IN THE NEW LABEL. ade WARNING: YOU MUST EXIT AND RE-ENTER THE VIEW TO GET THE NEW ENVIRONMENT.

11. beginmerge

Recommendation: Your view must be refreshed to the latest available label before you can run beginmerge. If you have created and/or removed any elements in your transaction, you must run the savetrans command before executing beginmerge. The beginmerge command will start merging the currently open transaction. It checks that the transaction can be merged, that every element is checked in, and that the view is refreshed to the latest label. In addition, this command locks the transaction from sharing or any other changes besides the merge process. It collects locks on all branched elements in the transaction and will warn for failed locks. You can run the command repeatedly until


all locks are acquired. The only commands allowed during the merge process that change the transaction are: mergetrans, endmerge, and abortmerge. Finally, beginmerge will check if the label series is enabled for gating by the merge request tool. If mergereq is enabled, beginmerge checks that the transaction has been submitted and approved. See the Merge Request Tool section for additional information on this check. Usage: ade beginmerge JDev navigation: Versioning > Beginmerge

12. mergetrans

This command merges the changes into the checked out versions on the system branch. Merges may be trivial or non-trivial. A trivial merge occurs when there are no intervening changes in the codeline since the element was checked out from the system branch. A non-trivial merge occurs when an intervening change has been made to the system branch since you checked out your element. In these cases, merge conflicts may occur. Review the Resolving PT merge or refresh conflicts section for additional information on conflict resolution.

Usage: ade mergetrans JDev navigation: Versioning > Mergetrans

13. Edit, build, and test

Perform this step as per your product’s development processes. You must verify and validate the contents of all files in your transaction before proceeding to the next step.

14. endmerge

This command finishes the process of merging the changes in a transaction into a system branch. Endmerge releases the locks and publishes the changes for inclusion in the next label. After this command completes, your view is restored to a label based state. The changes that you just merged in will be gone from your view. As soon as the next label comes out, you will be able to see your changes again.

Usage: ade endmerge JDev Navigation: Versioning > Endmerge

Merging

There are three types of merges:

• Trivial: When there are no changes to be merged, the file is simply copied as the merge result.

• Automatic: If a merge is required, ADE merges the changes automatically if there are no conflicts.

• Conflicting: If a merge is required and there are conflicts, ADE will open a GUI merge tool to help you resolve merge conflict and choose the right content for the resulting merge file.

Sharing transactions

In a shared transaction, there is one (and only one) owning view, and one or more other views sharing the transaction. In summary:

• The owner starts the transaction using the ade begintrans command. The view in which the transaction is created is called the owning view.

• Views other than the owning view may then use the ade sharetrans command.

Following are the main transaction sharing commands:

sharetrans Before executing this command, transaction owners must run the savetrans command. In addition, run describetrans to get the base label for the transaction and refresh your view to that label.


This command allows more than one user to collaborate on a transaction. Usage: ade sharetrans <txn_name> Transaction sharers whose transactions are forcibly ended by the transaction owner, need to rerun sharetrans using the –reshare argument in order to resume their work. If the transaction owner forcibly ended the shared transaction to refresh the view from another label, transaction sharers should refresh their view to that label prior to rerunning sharetrans. The describetrans command will show the new base label for the transaction. Usage: ade sharetrans –reshare

sync All transaction sharers need to run this command to see the changes made by other sharers of the transaction. The command brings the latest check ins from other transaction sharers into the developer’s own view. Usage: ade sync <filename>

endsharetrans

This command removes a sharing view from a transaction and allows the sharer to end participation in the shared transaction. Transaction sharers must end the transaction before the owner can refresh the view. If needed, the owner of the shared transaction can force out the sharing views by running this command against each shared view. The describetrans command will list the views sharing that transaction. Transaction sharers need to then rerun the sharetrans command with the –reshare argument in order to resume their work. Usage: ade endsharetrans –view <view_name> For more information on shared transactions review the section on Sharing Transactions in the ADE User’s Guide: http://ade.us.oracle.com/docs/adeUG/.

Merging transactions across branches

You may need to merge a transaction across a branch for a critical bug fix impacting other teams, or as requested by Fusion Release Engineering (FRE).To take a bug fix transaction made against a PT branch and apply it to the main branch, run begintrans with the -xbranchmerge argument. Following is an example of the command sequence up to the merge:

createview Create a view on the branch label to which the transaction is being merged, that is, the target branch label. Usage: ade createview –label <label> <view name>

useview Set the context to the created view. Usage: ade useview <view name>

begintrans As development work in ADE is grouped by transactions, use this command to start a transaction. Use one transaction for each logical unit of work, enhancement, or bug fix. Usage: ade begintrans –xbranchmerge -fromtrans <source_txn>

Additional commands

Here are some additional commands, listed alphabetically, that may be used in conjunction with the ones previously described.


abortmerge

This command returns the transaction to the state it was in before beginmerge was issued. All files retain any changes made to them before the merge process was started. This command is only available before running endmerge. Usage: ade abortmerge

aborttrans

Use this command to undo all the work done in a given transaction. After aborting a transaction, your view will be restored to a label view based on your last base label. If you aborted a new transaction, then the developer transaction branch associated with the transaction will be removed and all work done will be lost. If you aborted a re-opened transaction, then only the work done since you issued ade begintrans –reopen will be lost. This command cannot be run if you are merging, use abortmerge first. Usage: ade aborttrans

cmhelp If you encounter issues using ADE, use this command to automatically file an iSupport Service Request. The command automatically collects user and machine information as well as the last ADE command executed (along with its arguments). You can modify this information and provide additional details as needed. Usage: ade cmhelp

desc Use this command to list metadata for a specific object. Usage: ade desc –file <filename>

describetrans

This command provides a full description of the transaction state and all the files active in the transaction. Usage: ade describetrans <transaction_name>

destroyview

Use this command to destroy a view. Do not execute it within a view context. The view must not have an active transaction when this command is run. Usage: ade destroyview <view_name>

endtrans This command ends or closes out the transaction Usage: ade endtrans

lsco Use this command to list any files checked out in the transaction. Usage: ade lsco

lstrans This command lists ADE transactions owned by the user. Usage: ade lstrans

lsviews

This command lists the active transactions and views. Usage: ade lsviews


mkdir

This command creates new empty directories within a transaction. JDev performs this automatically as needed so command line usage is unnecessary. Usage: ade mkdir

mkelem

This command creates and initializes new files. JDev performs this automatically when you create new objects so command line usage is unnecessary. Usage: ade mkelem <filename>

pwv

This command displays view metadata including view name and location. The command runs against the current view by default. Include the output from this command in bugs filed against JDev. Usage: ade pwv –view <view_name>

rm This command removes the file from the next version of the parent directory. JDev performs this automatically when you remove a file so command line usage is unnecessary. Usage: ade rm <filename>

savetrans This command saves the current open ADE transaction to the backend version storage repository without merging to the system branch. It is recommended to run this command prior to beginning a merge, prior to transaction sharing, and before leaving for the end of the day if you have started to modify files in a transaction.

unbranch

Use this command to remove an element from the transaction and to cancel the checkout. Usage: ade unbranch <filename>

unco

This command will cancel the check out of the specified element and rolls back to the previously checked in version. Usage: ade unco <filename>

unmkelem

Use this command to undo the mkelem command and remove a newly created file from the transaction. Usage: ade unmkelem <filename> You also use this command to undo the mkdir command and remove a newly created directory from the transaction. Usage: ade unmkelem <dirname> For more details on these and other ADE commands, see the ADE Command Reference page: http://ade/twiki/bin/view/ADEFAQ/AdeCommandReference or, to get the most current usage information, use the –help argument.


Using ADE - for Integrators This section describes some of the common ADE related tasks an integrator may need to perform.

Configuring UIP

Create the necessary control files and customize the definitions for your product. Product specific UIP configuration files are version controlled in the intg directory under the product root directory. In Fusion Apps for example, the UIP setup files are under the fusionapps/intg directory. A product definition file is named the same as your product followed by the .def extension. It includes a parameters and expansion section. As part of initial product configuration, you provide values for the Announce_To and Integrator parameters. The Announce_To parameter is the destination mailing list for label announcements while the Integrator parameter provides the sender portion for those announcements. Here’s a sample product definition file:

# Copyright (c) 2008, Oracle. All rights reserved. # # Example UIP definitions. # [Parameters] Ade_Refreshview_Delay => 600 Ade_With_Latest_Link => 1 Announce_To => [email protected] Integrator => [email protected] Label_Timestamp => @<Label_Timestamp_Hour>@ Repos_Product => 1 Timestamp_Label_P => 1 Use_Stdout_Only => 1 Version => 2 [Expansions] compile => noop sanitize => noop archive => noop load => noop setup => noop make_sure => noop mk_xcscope_db => noop promote => noop labelzips => noop mkmanifest => noop verify => noop

Integration Commands

There are two broad categories of UIP commands.

• Direct integration and integration support commands.

• Label server manipulation commands.

Although most commands are automated, you should review them in order to better understand your product’s configuration files. See this page for a detailed list of UIP commands: http://aimeweb.us.oracle.com/intg-doc/reference/commands/index.html


Integration Tasks

Integration tasks are divided in two broad categories: plain tasks and tasks defined by integration modules. Module defined tasks are prefixed by the module name which always begins in upper case (for example, ADE:push or DO_Mgr:promote. Plain tasks do not contain colons and always begin in lowercase (for example, intgcs or dbpublish), See this page for a detailed list of UIP tasks: http://aimeweb.us.oracle.com/intg-doc/reference/tasks/index.html

Integration Parameters

UIP parameters control the functionality of UIP. Each task executed by UIP uses parameters to access items such as the name of the integrator and email addresses to which label announcements should be sent. Parameter information is usually queried from the task descriptions. There are two broad categories of parameters:

• Parameters associated with UIP modules.

• Regular UIP parameters.

See this page for a detailed list of UIP parameters: http://aimeweb.us.oracle.com/intg-doc/reference/parameters/index.html

Creating a PT

If you need to create a project transaction branch, send an email with new PT requirement justification to [email protected] requesting his approval. Once approved, he will provide you with the information you need, such as project ID, to run the create command.

create This command is executed outside a view. The user that invokes this command is recorded as the PT owner. PT owners receive email notifications when certain PT commands are run. Usage: farm project -create -baselabel <labelname> -projectid <projectid> -ptname <pt_name> -maillist <maillist>

Refreshing a PT branch from a label on its parent branch

This section provides an overview on how to refresh a PT branch from a label on its parent branch. Note that you cannot refresh a PT branch from a snapshot label. If you run into issues performing the steps, email problem details to [email protected]. In this example, the parent branch is FUSIONAPPS_PT.PRCM4_LINUX and the PT branches that need to refresh from it are as follows: FUSIONAPPS_PT.PRCPOM4_LINUX FUSIONAPPS_PT.PRCPONM4_LINUX FUSIONAPPS_PT.PRCPORM4_LINUX FUSIONAPPS_PT.PRCPOSM4_LINUX FUSIONAPPS_PT.PRCPOZM4_LINUX

beginrefresh

Start the refresh. This is similar to running ade refreshview. Run this command outside of an ADE view. This command will create an ADE view with name "<username>_pt_refresh.<pid>" for use in subsequent steps. Usage: farm project -beginrefresh -baselabel <label to refresh to> -ptname <pt_name> -parentseries <label series of parent label> -skip_ntcheck Example: farm project -beginrefresh -baselabel FUSIONAPPS_PT.PRCM4_LINUX_0804<DD.HHMM> -ptname PRCPOM4 -parentseries FUSIONAPPS_PT.PRCM4_LINUX –skip_ntcheck


useview

Run this command against the view created by beginrefresh. Review and resolve potential merge conflicts, if any. For assistance with merge conflict resolution, see the section on resolving PT merge or refresh conflicts. Usage: ade useview <view name>

endrefresh Finish the refresh. This should be executed in the view created by beginrefresh only when all merge conflicts have been resolved. Usage: farm project -endrefresh For more information on refreshing a PT branch see this page: http://staav14.us.oracle.com:9999/twiki/pub/INTEGTeam/ProjectTransactionsUserGuide/Project_Transactions.html#_Refreshing_a_PT_to%20a%20new%20parent%20bra

Merging a PT branch to its parent branch

This section provides an overview on how to merge a branch (label series) to its parent branch. If you run into issues performing the steps, email problem details to [email protected]. In this example, the parent branch is FUSIONAPPS_PT.PRCM4_LINUX and the PT branches that need to merge to it are as follows: FUSIONAPPS_PT.PRCPOM4_LINUX FUSIONAPPS_PT.PRCPONM4_LINUX FUSIONAPPS_PT.PRCPORM4_LINUX FUSIONAPPS_PT.PRCPOSM4_LINUX FUSIONAPPS_PT.PRCPOZM4_LINUX Each branch will have to refresh to the label that comes out in the FUSIONAPPS_PT.PRCM4_LINUX label series after all of them have merged. While following these steps, do not run any other ADE commands.

beginmerge

Start the merge (similar to the transaction beginmerge command). This needs to be done outside of an ADE view. This command will create an ADE view by name "<username>_pt_merge.<pid>" for use in subsequent steps. Usage: farm project -beginmerge -ptname <pt_name> -parentseries <label series of parent label> Example: farm project -beginmerge -ptname PRCPOM4 -parentseries FUSIONAPPS_PT.PRCM4_LINUX

useview Run this command against the view created by beginmerge. Usage: ade useview <view name>

merge Perform the merge. Review and resolve potential merge conflicts, if any. For assistance with merge conflict resolution, see the section on resolving PT merge or refresh conflicts. Usage: farm project –merge

endmerge Finish the merge. This is similar to the transaction endmerge command. This should be done in the same view where the merge was done, only when all merge conflicts have been resolved. Usage: farm project –endmerge For more information on merging a PT to its parent branch see: http://staav14.us.oracle.com:9999/twiki/pub/INTEGTeam/ProjectTransactionsUserGuide/Project_Transactions.html#_Merging_a_PT_to%20its%20parent%20branch


Aborting a PT merge or refresh

The beginmerge and beginrefresh commands lock the PT branch. Users cannot proceed with any activity on that PT branch while it’s locked. Run the following commands to unfreeze the branch and abort the transaction associated with that PT branch:

abortrefresh

Run this command in the view created by beginrefresh. Usage: farm project –abortrefresh

abortmerge

Run this command in the view created by beginmerge. Usage: farm project –abortmerge

Resolving PT merge or refresh conflicts

An integrator may need to resolve code merge conflicts which could occur during a merge down and refresh. Review the following example for steps to resolve such merge conflicts. Refresh the view to RDBMS_MAIN_LINUX_080222 and share the main refresh transaction. Example: ade sharetrans chliang_21956_refresh Run the lsconflicts command to identify the conflicts (both resolved and unresolved) associated with the transaction created during beginrefresh. The list contains only those files generated in the *.remerge_report.txt by ADE during beginrefresh. The user who initiated beginrefresh can run this command, reassign conflicts if necessary, and then run this command using the notify option to advise all involved users of the unresolved conflicts. Usage: farm project –lsconflicts [-resolved|-unresolved|-notify <ptowner|all> |-user <username>|-txn <txnname>] Use the resolved option to list only the resolved conflicts. Use the unresolved option to list only unresolved conflicts. The notify option allows the PT owner/user (who initiated beginrefresh) to notify users against whom unresolved conflicts are marked. Depending on whether resolved|unresolved was chosen, the command displays the relevant information. However, regardless of the option, if notify is specified, notification is sent only about unresolved conflicts. Valid notify option values are [ptowner|all]. If ptowner is specified, notifications are sent to the ptowner only. If all is specified, notifications are sent to all the users associated with unresolved conflicts. Note that the user who initiated beginrefresh always receives all the emails. The user option allows querying of conflicts only against a particular user. If this option is used, -notify all would correspond only to the user specified. The user needs to specify the txn name if the command is being run from outside of a view (or from a view that’s not associated with any transaction). By default, the transaction associated with the view is chosen. Remerge the files assigned to you and resolve the conflicts. Usage: ade merge -remerge [filename] –xmerge Perform a sanity check on the files you resolved, for example, recompile the file if possible and diff the file against MAIN and PT.XS labels. Check in the resolved file. Usage: ade ci [filename] Mark the file resolved. The filename value should be the full path to the filename you see in the merge conflict list. There are currently no restrictions on who can mark the conflict as resolved/unresolved. Usage: farm project -mark resolved -filename [filename] Example: farm project -mark resolved -filename rdbms/admin/xxxx.sql End the shared transaction once all the files assigned to you are resolved.


Example: ade endsharetrans Here are some additional commands to help you with the conflict resolution process:

reassign

The project transaction owner who initiated the beginrefresh runs this command to reassign conflicts to another user. The user to whom the conflict is reassigned has to be an LDAP user. You cannot assign a conflict to an AIMEWEB ID. Usage: farm project –reassign –filename <filename> -user <user> [-notify <ptowner|all>] [-txn <txnname>] [-comments] Use the notify option to send an email to the newly assigned user as well as the user to whom the conflict was originally assigned. You can specify “all” to notify all users including the PT owner or you can specify “ptowner” to only notify the project transaction owner. conflicthistory Use this command to query the history of reassignments and marks made against a particular file. Usage: farm project –conflicthistory –filename –reassign|-filestatus [-txn <txnname>] Reassignment history is retrieved using the reassign option. This will display the user to whom the file is assigned, the user who performed the reassignment, activity timestamps, and comments passed during the reassignment, if any. The history of file "marking" as resolved/unresolved is obtained through the filestatus option. This displays the user who marked the file, the status of the file (resolved/unresolved), activity timestamps, and comments passed during the mark command, if any.

Using the merge request (mergereq) tool

As mentioned in the Integration section of this guide, the merge request tool acts as a gating facility to keep the main codeline stable. If you enable it for use, the ADE beginmerge command will only execute if a merge request has been submitted and approved.

Prerequisites and configuration

Here are the prerequisites for using mergereq:

• Mount /usr/local/packages/mergereq on your workstation. No action should be needed for this step since mergereq is mounted on each workstation.

• Obtain an AIMEWEB account for accessing the Merge Request Approval tool. No action should be needed for this step. Application developers should already have an account.

• Enable merge request for your product. See the Merge Request User Guide for details: http://staav14.us.oracle.com:9999/twiki/bin/view/AIMEWEB/MergeReqEnable.

Follow the support process outlined in the Merge Request User Guide to get assistance with your initial configuration: http://staav14.us.oracle.com:9999/twiki/bin/view/AIMEWEB/MRUserGuide#Support_Process.

Running mergereq

Developers submit the merge request from within an ADE view. Usage: mergereq –y –m <manager firstname.lastname> –r <release manager firstname.lastname> See the Submission tool section of the Mergereq User Guide for additional information: http://staav14.us.oracle.com:9999/twiki/bin/view/AIMEWEB/MRUserGuide#Submission_tool.

If mergereq is enabled for your product and you don’t submit a merge request prior to running beginmerge, the beginmerge command will fail. See the Integration with ADE section in the Merge Request User Guide for details on the various error scenarios and corresponding error messages: http://staav14.us.oracle.com:9999/twiki/bin/view/AIMEWEB/MRUserGuide#Integration_with_ADE.


Designated approvers then use the Mergereq Approval tool to manage the submitted requests. See the Approval Tool and Workflow concept sections of the Merge Request User Guide for details on this process including sample screenshots: http://staav14.us.oracle.com:9999/twiki/bin/view/AIMEWEB/MRUserGuide#Approval_Tool.


Getting Help Various resources are available to assist you if you encounter issues using ADE. Review Table 3 for resource details.

Table 3 - Available Resources

Resource Additional information

Troubleshooting ADE/JDev problems

http://ade.us.oracle.com/twiki/bin/view/FusionApps/TroubleShooting

Known issues and workarounds

http://ade.us.oracle.com/twiki/bin/view/ADEFAQ/CurrentIssues

Unassigned cmhelp ticket queue

http://ade.us.oracle.com/twiki/bin/view/SUPPORTTEAM/WorkQueue

File a support request using the ade cmhelp command

This command automatically collects relevant information and opens an iSupport Service Request.

Using ade cmhelp: http://ade.us.oracle.com/twiki/bin/view/ADEFAQ/GenAdeQ001#ade_cmhelp

Priority guidelines: http://ade.us.oracle.com/twiki/bin/view/ADEFAQ/GenAdeQ001#ADE_iSupport_Ticket_priorities

ADE User Guide

PDF: http://ade.us.oracle.com/twiki/pub/ADE32/WebHome/ADE_UG_321.pdf HTML: http://ade.us.oracle.com/docs/adeUG/

ADE/SCS FAQ

http://ade.us.oracle.com/twiki/bin/view/ADEFAQ/AdeScsFAQ

SCS to ADE command reference guide

http://ade.us.oracle.com/twiki/bin/view/ADEFAQ/AdeScsCmds

ADE FAQ and support page

http://ade.us.oracle.com/twiki/bin/view/ADEFAQ/WebHome

ADE Forums

Use the ADE for Fusion Apps forum for Fusion Apps specific ADE related questions. http://myforums.oracle.com/jive3/forum.jspa?forumID=2899 Use the ADE forum for general ADE discussion topics, not for requesting support. http://myforums.oracle.com/jive3/forum.jspa?forumID=2741

Support for JDev issues

File a bug against product 807, component JDEV. Include output from the ade pwv command.

For issues encountered when: 1) refreshing a PT branch from a label on the parent 2) merging a PT branch to its parent branch

Send issue details to: [email protected]

Date post:	02-Jan-2016
Category:	Documents
Upload:	srikanth-kalla
View:	4,276 times
Download:	54 times

ADE Getting Started

Documents