Oracle APEX Source Control Strategy

Objective: Define the strategy the development team should use with regards to source control for all applications written with Oracle Application
Express.

I. Repository Structure
II. Developing, Committing Code, and Branching
The dev Branch:
Feature Branches
Merging Feature Branches into the Dev Branch
The test Branch:
The release Branch:

I. Repository Structure
Each APEX application will have a corresponding mercurial repository in Bitbucket. The repository should follow the below repository structure:

project-root

ddl/

dml/

packages/

snippets/

queries/

unit_tests/

scripts/

views/

f<<APP_ID>>.sql

00_install.sql

The explanation behind what each of these directories is for / what belongs in them is listed in the README.md file of the APEX - Test Repository
repo, but in case you have problems accessing that, we will also provide this explanation here:

README.md
# Author - Jeff Johnson (PDI)
# Date - 01.22.2019

######################################################################
# DDL #
######################################################################

The DDL directory should contain only creation of database objects

relating to
table changes, sequences, triggers, and indexes. Each table created should
have
its own script file including the table creation, any indexes,
materialized view logs,
sequences, and triggers. For example:

* my_table.sql

create table my_table (

my_pk number,
my_value varchar2 (50),
constraint mt_pk primary key (my_pk)
);

create sequence mt_s start with 1 increment by 1;

create materialized view log on my_table with primary key, rowid;

create or replace trigger mt_biur_trg

before insert
or update
on my_table
for each row
begin
if inserting then
:new.my_pk := mt_s.nextval;
end if;
end mt_biur_trg;

######################################################################
# DML #
######################################################################

The DML directory should contain only scripts that populate tables,
including
the creation of scheduled jobs. Scripts here must be used for production
data fixes,
population of catalog/lookup tables, or creation of DBMS jobs. Any DML used
for populating dummy / test data should be stored in the snippets
directory.

* my_job.sql

declare
l_job_name varchar2 (250) := 'MY_JOB';
l_job_type varchar2 (250) := 'PLSQL_BLOCK';
l_job_action varchar2 (250) := 'BEGIN DBMS_OUTPUT.PUT_LINE
(''hello, world!''); END;';
l_start_date date := trunc (sysdate + 1) + .5/24;
l_repeat_interval varchar2 (250) := 'FREQ=DAILY';
l_end_date date := to_date (null);
l_job_class varchar2 (250) := 'DEFAULT_JOB_CLASS';
l_enabled boolean := true;
l_auto_drop boolean := false;
l_comments varchar2 (500) := 'My job!';
begin
begin
dbms_scheduler.drop_job (l_job_name);
exception
when others then
null;
end;
dbms_scheduler.create_job (
job_name => l_job_name,
job_type => l_job_type,
job_action => l_job_action,
start_date => l_start_date,
repeat_interval => l_repeat_interval,
end_date => l_end_date,
job_class => l_job_class,
enabled => l_enabled,
auto_drop => l_auto_drop,
comments => l_comments
);
exception
-- Raise unexpected error
when others then
raise_application_error (-20001, 'ERROR IN FILE dml/my_job.sql: COULD
NOT CREATE JOB FOR THE FOLLOWING REASON: ' || sqlerrm);
end;

######################################################################
# PACKAGES #
######################################################################

This directory should be used exclusively for packages to be compiled. No

test / dummy packages
should reside here, only packages that would be used in production. All
packages must be split
into two files: the package spec and the package body

* my_package.pks

create or replace package my_package as

/****************************************************************
* Author - Jeff Johnson (PDI)
* Date - 01.22.2019
* Description - My package!
*
 * Change Log
*
* Author Date Description
* --------- ------------- --------------------
* Jeff Johnson (PDI) 01.22.2019 Package Creation
***************************************************************/

/*
Author - Jeff Johnson (PDI)
Date - 01.22.2019
Description - Prints an input message
*/

procedure my_procedure (
p_message in varchar2
);

end;

* my_package.pkb

create or replace package body my_package as

procedure my_procedure (
p_message in varchar2
)
as
begin
dbms_output.put_line (p_message);
end my_procedure;

end;

######################################################################
# SNIPPETS #
######################################################################

Snippets are used for production ready scripts and unit tests (for non-
production use) / misc non production code.
Within this directory are three subdirectories, "scripts", "queries", and
"unit_tests":

Scripts:
Should include production ready scripts that are to be run in
production

Queries:
Should include .sql files that can be re-used to help speed up
development.

Unit_tests:
Should include .sql files meant for unit testing PL/SQL procedures in
developed packages.
* ./scripts/my_script.sql

set serveroutout on;

declare
l_the_variable constant varchar2 (50) := 'MY_SCRIPT';
begin
dbms_output.put_line (l_the_variable);
end;

* ./queries/my_query.sql

with
my_in_memory_table
as (
select 1 my_column
from dual
)
select my_in_memory_table.my_column
from my_in_memory_table;

* ./unit_tests/my_package/my_procedure/1.sql

set serveroutput on;

declare
l_test_message const varchar2 (50) := 'MY_PROCEDURE_UNIT_TEST';
begin
my_package.my_procedure (
p_message => l_test_message
);
end;

######################################################################
# VIEWS #
######################################################################

This directory should exclusively include intended production views

* my_view.sql

create or replace view my_view

as
with
my_in_memory_table
as (
select 1 my_column
from dual
)
select my_in_memory_table.my_column
from my_in_memory_table;

######################################################################
# 00_INSTALL.SQL #
 ######################################################################

This script should include * all * code required for a production release,
which should include all packages, all views, all DBMS_JOBS, and any
*NEW* DDL or DML scripts.
All views, packages, and jobs, whether or not they have been changed,
should be
re-runnable in production. This reduces the complexity of maintaining the
install script over time.

The order in which scripts should be executed from this file is as

follows:

1 - DDL
2 - Package Specs
3 - Views
4 - Package Bodies
5 - DML
6 - APEX application file
7 - Snippets/Scripts

* 00_install.sql

set define off;

@@"ddl/my_table";

-- START NOTES: THESE MAY GROW / MORE MAY BE ADDED, BUT NOTHING SHOULD BE
REMOVED UNLESS DEPRECATED

@@"packages/my_package.pks";

@@"views/my_view";

@@"packages/my_package.pkb";

@@"dml/my_job";

-- END NOTES

@@"f<<MY_APEX_APP_ID>>"; -- APEX application file

 /

@@"snippets/scripts/my_script";

II. Developing, Committing Code, and Branching

Each repository should include a DEV, TEST, and RELEASE branch:

The dev Branch:

Feature Branches
The maintenance of the DEV branch should be the primary focus of the development team. This branch should always maintain a set of working
code comprising multiple features / fixes not yet migrated to the TEST environment. For each feature / small set of features that gets worked on
by an individual, we should create a branch off of the dev branch and name it according to the work that will be done. The steps to do this are as
follows:

How to branch off of DEV

1. Within the DEV branch, click the "Branch" feature in sourcetree

2. Enter the name of your branch

 3. After the branch is created, immediately commit it, and then push it:

Pull Requests

Merging Feature Branches into the Dev Branch

After your branch has been created, you can make the code changes required to satisfy the feature / fix you are working on. After the changes
have been made, we will want to pull the dev branch into our branch. We do this because while we were making changes, another developer
may have also made changes that might have been pushed to the dev branch. Pushing our changes to the dev branch would then possibly
create a code conflict. As much as possible, we need to keep code conflicts away from our main branches (dev, test, release), and
handle them in our own. The below illustrates how to merge the dev branch into your own.

How to pull the dev branch into your branch

Once dev has been merged into your branch, resolve any conflicts (ideally there are none). At this stage, you should have your changes plus any
changes other developers have made and pushed to the dev branch. Commit your code and push it (the open file changes should be those
created by the merge).

Now your code should be ready to be merged into the Dev branch. Log into Bitbucket and navigate to your repository. Then, click the "Pull
Request" tab, and create a pull request:

Pull Requests

When creating a pull request, Bitbucket should automatically select your source branch (it should know what your latest modified branch was -
this is tied to your account); nonetheless you should select your feature / fix branch as the source branch and the "dev" branch as the destination
branch. This will create a request to merge your branch into the dev branch, appending your features / fixes:

Pull Request Creation

Note that the title / details of the pull request will be automatically populated per the comments on your branch's commits. For example, in my
branch, I committed code with a message stating "Made a tiny change." In this pull request, this automatically populated. This helps the reviewer
of a pull request understand what code will be merged into a pull request.

Also note that the "Close branch" checkbox is checked. For only our own feature / fixes branches, we should always check this box. This
will result in this branch being closed / destroyed once the merge to dev has been completed, which helps keep the repository relatively clean. We
should never elect to do this when merging dev into test or test into release via pull requests, but the development team should never
need to worry about making these pull requests.

After the pull request has been made, a reviewer / lead should be contacted, and that person should review the contents of the pull request and
approve it:

Approving and Merging a Pull Request

Once the pull request has been merged, the feature has been fully closed out and now exists in our core code base for the development
environment.

The test Branch:

The development team should group features / fixes in reasonably sized batches for migrating code between Dev and Test. For example, out of
10 requirements, I may elect to have a team of three each work on one, and when each one is completed, that group will be migrated to the Test
environment. This means that there would be three pull requests into the Dev branch, and once this has been completed, the code should be
migrated to Test, and a pull request should be made to pull Dev into Test. Note that we will never elect to close the source branch (dev)
when pulling dev into test. The process for the pull request is no different from the process to pull code into the Dev branch from feature
branches with the exception of the person doing it. A designated person should make pull requests into the Test branch and review the changes
going in (this will be every pull request from feature branches to dev since the last pull request from dev to test).

The release Branch:

Once all code required for a release has been written, migrated to the Test environment, and validated by the QA team, a pull request can be
made from the Test branch to the Release branch following the same process as the Dev to Test pull request strategy. Note that we will never
elect to close the source branch (test) when pulling test into release. Code in the release branch will be the only code ever run in production.