Update of CONTRIBUTING.md. Fixed developer scripts.

utPLSQL · jgebal · Aug 26, 2017 · Aug 22, 2017 · Aug 23, 2017 · Aug 25, 2017
commit 4a1d223cedb81fbd36e00f8e7b1ce2e1384f30e2
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -50,77 +50,79 @@ We use four different database accounts (users) for development process.
 
 
 
-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._
+### To get started with development, follow the below steps.
 
+_If you're using Windows, run the shell scripts using `GIT bash` - Windows-based bash command line._
+
+**Clone your fork of utPLSQL git repository** 
 ```bash
 # clone your fork of utPLSQL
 git clone https://github.com/your account/utPLSQL.git utPLSQL
 
 cd utPLSQL
 
-# add main porject repo as upstream
+# add main project 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 utPLSQL_latest_release
-
-# 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 
+**Prepare environment script**
 
+Copy the environment variables template `development/template.env.sh` to `development/env.sh` 
+```bash
+cp development/template.env.sh development/env.sh
+chmod u+w development/env.sh
 ```
 
-Now copy the file `development/template.env.sh` to `development/env.sh` and adjust variables to match your local needs.
-You might have to adjust the following lines:
-
-````bash
+You might have to adjust the following lines in `development/env.sh`:
+```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
-````
+```
+
+**Download utPLSQL release sources and utplsq-cli**
 
-Refreshing your local repo.
+_The below script is fetching latest release version from utPLSQL repository. Latest release version is used for self-testing._
 ```bash
-# fetch all remote repositories
-git fetch --all
+development/refresh_sources.sh
+```
 
-# 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
+**Setup local database for utPLSQL development**
+```bash
+development/install.sh
+```
 
-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 
+That's it! You now have the following:
+- sources from `develop` branch of your fork of utPLSQL repository in `utPLSQL/ut3_latest_release` directory
+- sources from `master` branch of utPLSQL/utPLSQL repository in `utPLSQL/ut3_latest_release` directory
+- binaries of `utplsql-cli` in `utPLSQL/utPLSQL-cli` directory
+- database users created
+- utPLSQL develop version deployed to `ut3` schema
+- utPLSQL released version deployed to `ut3_latest_release`
 
-```
+At any time, if you need to refresh your database, the below scripts might be helpful. 
 
-Cleanup of utPLSQL installation (call from your base repo directory).
+### Cleanup of utPLSQL installation in local database
 ```bash
 development/cleanup.sh
 ```
 
-Install utPLSQL for development (call from your base repo directory)
+### Reinstalling utPLSQL development in `ut3` schema
 ```bash
-development/install.sh
+development/refresh_ut3.sh
 ```
 
-Reinstalling utPLSQL development in `ut3` schema (call from your base repo directory).
-```bash
-development/refresh.sh
-```
+Whenever a new version of utPLSQL or a new version of utPLSQL-cli is available, use `development/refresh_sources.sh` to refresh files in your local project folders.  
 
 ## Modules ##
 
+Below diagram gives a high-level overview of utPLSQL v3 modules and their dependencies.
+Dependencies to `ut_util` are not shown as most of modules are depending on it.
+
 ![utPLSQL V3 Modules](development/utPSLQLv3-modules.png)
 
 

diff --git a/development/cleanup.sh b/development/cleanup.sh
@@ -1,7 +1,9 @@
 #!/usr/bin/env bash
-cd $(git rev-parse --show-cdup)
 
-development/env.sh
+#goto git root directory
+git rev-parse && cd "$(git rev-parse --show-cdup)"
+
+. development/env.sh
 
 "${SQLCLI}" sys/${ORACLE_PWD}@//${CONNECTION_STR} AS SYSDBA <<-SQL
 drop user ${UT3_OWNER} cascade;

diff --git a/development/install.sh b/development/install.sh
@@ -1,9 +1,12 @@
 #!/usr/bin/env bash
 
-cd $(git rev-parse --show-cdup)
+#goto git root directory
+git rev-parse && cd "$(git rev-parse --show-cdup)"
+
+. development/env.sh
 
-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/readme.md b/development/readme.md
diff --git a/development/refresh_sources.sh b/development/refresh_sources.sh
@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+
+#goto git root directory
+git rev-parse && cd "$(git rev-parse --show-cdup)"
+
+. development/env.sh
+
+# remove sub-direcotry containing master branch shallow copy
+rm -rf ${UTPLSQL_DIR:-utPLSQL_latest_release}
+# clone utPLSQL master branch from upstream into utPLSQL sub-directory of your project
+git clone --depth=1 --branch=${SELFTESTING_BRANCH:-master} https://github.com/utPLSQL/utPLSQL.git ${UTPLSQL_DIR:-utPLSQL_latest_release}
+
+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 u+x utPLSQL-cli/bin/utplsql && rm utPLSQL-cli.zip
+
diff --git a/development/refresh.sh → development/refresh_ut3.sh b/development/refresh.sh → development/refresh_ut3.sh
@@ -1,8 +1,9 @@
 #!/usr/bin/env bash
 
-cd $(git rev-parse --show-cdup)
+#goto git root directory
+git rev-parse && cd "$(git rev-parse --show-cdup)"
 
-development/env.sh
+. development/env.sh
 
 cd source
 

diff --git a/development/template.env.sh b/development/template.env.sh
@@ -1,12 +1,12 @@
 #!/usr/bin/env bash
 
-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 # Adjust your local SYS password
 
-
+export UTPLSQL_DIR="utPLSQL_latest_release"
+export SELFTESTING_BRANCH=master
 export UT3_OWNER=ut3
 export UT3_OWNER_PASSWORD=ut3
 export UT3_RELEASE_VERSION_SCHEMA=ut3_latest_release