utPLSQL · jgebal · Aug 26, 2017 · Aug 22, 2017 · Aug 23, 2017 · Aug 25, 2017
diff --git a/.gitignore b/.gitignore
@@ -12,3 +12,6 @@ release/
 *.gz
 *.zip
 node_modules/
+utPLSQL/
+utPLSQL-cli/
+
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,169 @@
+## How to contribute ##
+
+The following are the guidelines everyone should use to contribute to utPLSQL.  
+Changes are welcome from all members of the Community. 
+
+## Getting Started ##
+
+1. Create a [GitHub Account](https://github.com/join).
+2. Fork the utPLSQL Repository and setup your local Repository.
+     * Each of the steps below are detailed in the [how to Fork](https://help.github.com/articles/fork-a-repo) article!
+     * Clone your Fork to your local machine.
+     * Configure "upstream" remote to the [utPLSQL repository](https://github.com/utPLSQL/utPLSQL.git).
+3. For each change you want to make:
+     * Make sure your forked repository is up to date with upstream before you start coding. See [syncing your local repository](https://help.github.com/articles/syncing-a-fork) with upstream utPLSQL repository.
+     * Create a new branch for your change. We use `feature/feature_name` or `bugfix/fixed_issue_name` to identify branch types.
+     * Make your change in your new branch. 
+     * Make sure your change is covered with unit tests.
+     * **Verify code compiles and all existing and new unit tests pass.**
+         * The quickest way to have a Pull Request not approved, is to submit code that does not compile or pass tests.
+     * Commit change to your local repository.
+     * Push change to your remote repository.
+     * Submit a [Pull Request](https://help.github.com/articles/using-pull-requests) into develop branch.
+     * Note: local and remote branches can be deleted after pull request has been merged.
+
+## Coding Standards ##
+
+* We use snake case for all identifiers in PLSQL code. This separates keywords in names with underscores.  `execute_test`
+* All code is lower case.
+* Prefixes:
+	* Arguments to procedures and functions will start with `a_` an Example would be procedure `is_valid(a_owner_name varchar2)`
+	* Object types and packages will start with `ut_`
+	* Local variables `l_`
+	* Global variables `g_`
+	* Global Constants start with `gc_`
+	* Types in packages, objects start with `t_`
+	* Nested Tables start with `tt_`
+* varchar2 lengths are set in characters not bytes 
+
+
+## Configuring local environment ##
+
+Your local environment can be of any flavor (Unix/Linux/Windows/Mac). 
+At minimum you need to have Oracle database 11.2 XE accessible for the project and SYS account access to install and develop utPLSQL.
+
+We use four different database accounts (users) for development process.
+* `ut3_latest_release` - holds latest released version of utPLSQL. This schema holds the testing framework used for self-testing of utPLSQL development.
+* `ut3` - holds latest (current) development version of utPLSQL. This is the schema you will be working on.
+* `ut3_tester` - holds unit test packages for development of utPLSQL.
+* `ut3$user#` - used for testing accessibility to schema names with special characters.
+
+
+
+Snippet to get you started with development.
+
+_If you're using Windows, you can run below scripts using `GIT bash` - Windows-based Unix-like command line._
+
+```bash
+# clone your fork of utPLSQL
+git clone https://github.com/your account/utPLSQL.git utPLSQL
+
+cd utPLSQL
+
+# add main porject repo as upstream
+git remote add upstream https://github.com/utPLSQL/utPLSQL.git
+
+# fetch all remote repositories
+git fetch --all
+
+# clone utPLSQL master branch from upstream into utPLSQL sub-directory of your project
+git clone --depth=1 --branch=master https://github.com/utPLSQL/utPLSQL.git
+
+# download beta version of utPLSQL-cli
+curl -Lk -o utPLSQL-cli.zip https://bintray.com/viniciusam/utPLSQL-cli/download_file?file_path=utPLSQL-cli-develop-test3.zip
+# unzip utPLSQL-cli and remove the zip file
+unzip utPLSQL-cli.zip && chmod -R u+x utPLSQL-cli && rm utPLSQL-cli.zip 
+
+```
+
+Now adjust the file ``development/env.sh`` to match your local needs.
+You might have to adjust the following lines:
+
+````bash
+export SQLCLI=sql # For sqlcl client
+#export SQLCLI=sqlplus # For sqlplus client
+export CONNECTION_STR=127.0.0.1:1521/xe # Adjust the connect string
+export ORACLE_PWD=oracle # Adjust your local SYS password
+````
+
+Refreshing your local repo.
+```bash
+# fetch all remote repositories
+git fetch --all
+
+# remove sub-direcotry containing master branch shallow copy
+rm -rf utPLSQL
+# clone utPLSQL master branch from upstream into utPLSQL sub-directory of your project
+git clone --depth=1 --branch=master https://github.com/utPLSQL/utPLSQL.git
+
+rm -rf utPLSQL-cli/*
+# download beta version of utPLSQL-cli
+curl -Lk -o utPLSQL-cli.zip https://bintray.com/viniciusam/utPLSQL-cli/download_file?file_path=utPLSQL-cli-develop-test3.zip
+# unzip utPLSQL-cli and remove the zip file
+unzip utPLSQL-cli.zip && chmod -R u+x utPLSQL-cli && rm utPLSQL-cli.zip 
+
+```
+
+Cleanup of utPLSQL installation (call from your base repo directory).
+```bash
+development/cleanup.sh
+```
+
+Install utPLSQL for development (call from your base repo directory)
+```bash
+development/install.sh
+```
+
+Reinstalling utPLSQL development in `ut3` schema (call from your base repo directory).
+```bash
+development/refresh.sh
+```
+
+## Build Environment ##
+
+We are using private docker images to test utPLSQL for our Travis CI builds. The following versions of Oracle Database are being used.
+
+* 11g XE R2
+* 12c SE R1
+* 12c SE R2
+
+These images are based on the slimmed versions [official dockerfiles released by Oracle](https://github.com/utPLSQL/docker-scripts), but due to licensing restrictions, we can't make the images public.
+You can build your own and use it locally, or push to a private docker repository.
+
+The build steps are simple if you already have some experience using Docker. You can find detailed information about how to build your own image with a running database in: [example of creating an image with pre-built DB](https://github.com/oracle/docker-images/blob/master/OracleDatabase/samples/prebuiltdb/README.md)
+
+> You can find more info about the official Oracle images on the [Oracle Database on Docker](https://github.com/oracle/docker-images/tree/master/OracleDatabase) GitHub page.
+
+> If you are new to Docker, you can start by reading the [Getting Started With Docker](https://docs.docker.com/engine/getstarted/) docs.
+
+### Docker Build Notes ###
+
+* You need to comment out the VOLUME line. This step is required, because volumes are not saved when using `docker commit` command.
+* When the build process is complete, you will run the container to install the database. Once everything is set up and you see the message "DATABASE IS READY!", you may change the password and stop the running container. After the container is stopped, you can safely commit the container.
+* You can use the --squash experimental docker tag to reduce the image size. Example:
+```
+docker build --force-rm --no-cache --squash -t oracle/db-prebuilt .
+```
+
+Travis will use your Docker Hub credentials to pull the private images, and the following secure environment variables must be defined.
+
+Variable | Description
+---------|------------
+**DOCKER_USER**<br />**DOCKER_PASSWORD** | _Your Docker Hub website credentials. They will be used to pull the private database images._
+
+### SQLCL ###
+
+Our build configuration uses SQLCL to run the scripts, and you need to configure a few additional secure environment variables. After the first build, the downloaded file will be cached.
+
+Variable | Description
+---------|------------
+**ORACLE_OTN_USER<br />ORACLE_OTN_PASSWORD** | _Your Oracle website credentials. They will be used to download SQLCL._
+
+
+## New to GIT ##
+
+If you are new to GIT here are some links to help you with understanding how it works.    
+
+- [GIT Documentation](http://git-scm.com/doc)
+- [Atlassian Git Tutorial](https://www.atlassian.com/git/tutorial/git-basics)
+- [What are other resources for learning Git and GitHub](https://help.github.com/articles/what-are-other-good-resources-for-learning-git-and-github) 
diff --git a/development/cleanup.sh b/development/cleanup.sh
@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+cd $(git rev-parse --show-cdup)
+
+development/env.sh
+
+"${SQLCLI}" sys/${ORACLE_PWD}@//${CONNECTION_STR} AS SYSDBA <<-SQL
+drop user ${UT3_OWNER} cascade;
+drop user ${UT3_RELEASE_VERSION_SCHEMA} cascade;
+drop user ${UT3_TESTER} cascade;
+drop user ${UT3_USER} cascade;
+
+begin
+  for i in (
+    select decode(owner,'PUBLIC','drop public synonym "','drop synonym "'||owner||'"."')|| synonym_name ||'"' drop_orphaned_synonym from dba_synonyms a
+     where not exists (select null from dba_objects b where a.table_name=b.object_name and a.table_owner=b.owner )
+       and a.table_owner in ('${UT3_OWNER}','${UT3_RELEASE_VERSION_SCHEMA}','${UT3_TESTER}','${UT3_USER}')
+  ) loop
+    execute immediate i.drop_orphaned_synonym;
+  end loop;
+end;
+/
+exit
+SQL
diff --git a/development/env.sh b/development/env.sh
@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+
+export UT3_OWNER=ut3
+export UT3_OWNER_PASSWORD=ut3
+export UT3_RELEASE_VERSION_SCHEMA=ut3_latest_release
+export UT3_TESTER=ut3_tester
+export UT3_TESTER_PASSWORD=ut3
+export UT3_TABLESPACE=users
+export UT3_USER="UT3\$USER#"
+export UT3_USER_PASSWORD=ut3
+export UTPLSQL_DIR="utPLSQL_latest_release"
+export SQLCLI=sql # For sqlcl client
+#export SQLCLI=sqlplus # For sqlplus client
+export CONNECTION_STR=127.0.0.1:1521/xe # Adjust the connect string
+export ORACLE_PWD=oracle
+
diff --git a/development/install.sh b/development/install.sh
@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+
+cd $(git rev-parse --show-cdup)
+
+development/env.sh
+development/cleanup.sh
+.travis/install.sh
+.travis/install_utplsql_release.sh
+.travis/create_additional_grants_for_old_tests.sh
diff --git a/development/refresh.sh b/development/refresh.sh
@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+
+cd $(git rev-parse --show-cdup)
+
+development/env.sh
+
+cd source
+
+"${SQLCLI}" sys/${ORACLE_PWD}@//${CONNECTION_STR} AS SYSDBA <<-SQL
+@uninstall ${UT3_OWNER}
+@install ${UT3_OWNER}
+exit
+SQL
diff --git a/development/utPSLQLv3-modules.png b/development/utPSLQLv3-modules.png
diff --git a/docs/about/CONTRIBUTING.md b/docs/about/CONTRIBUTING.md
diff --git a/docs/about/project-details.md b/docs/about/project-details.md
@@ -9,7 +9,7 @@
 utPLSQL is open source project [hosted on GitHub](https://github.com/utPLSQL/utPLSQL).
 
 Contributions, help and constructive feedback is always appreciated.
-If you are interested in helping please read our [guide to contributing](CONTRIBUTING.md)
+If you are interested in helping please read our [guide to contributing](https://github.com/utPLSQL/utPLSQL/CONTRIBUTING.md)
 
 
 
diff --git a/docs/index.md b/docs/index.md
@@ -21,7 +21,6 @@ The framework follows industry standards and best patterns of modern Unit Testin
        - [License](about/license.md)
        - [Support](about/support.md)
        - [Authors](about/authors.md)
-       - [Contributing](about/CONTRIBUTING.md)
 
 # Demo project
 

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -28,4 +28,3 @@ pages:
        - License: about/license.md
        - Support: about/support.md
        - Authors: about/authors.md
-       - Contributing: about/CONTRIBUTING.md
diff --git a/readme.md b/readme.md
@@ -156,7 +156,7 @@ Finished in .036027 seconds
 # Contributing to the project
 
 We welcome new developers to join our community and contribute to the utPLSQL project.
-If you are interested in helping please read our [guide to contributing](docs/about/CONTRIBUTING.md)
+If you are interested in helping please read our [guide to contributing](CONTRIBUTING.md)
 The best place to start is to read the documentation and get familiar with the existing code base.
 A [slack chat](https://utplsql.slack.com/) is the place to go if you want to talk with team members.
 To sign up to the chat use [this link](http://utplsql-slack-invite.herokuapp.com/)