Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 0d017be

Browse files
jgebaljgebal
committed
Moved CONTRIBUTING.md to project root to conform with github project standards.
Updated `CONTRIBUTING.md` with additional info on project setup.
1 parent 516ea5f commit 0d017be

2 files changed

Lines changed: 127 additions & 25 deletions

File tree

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,6 @@ release/
1212
*.gz
1313
*.zip
1414
node_modules/
15+
utPLSQL/
16+
utPLSQL-cli/
17+

‎CONTRIBUTING.md‎

Lines changed: 124 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -7,31 +7,27 @@ Changes are welcome from all members of the Community.
77

88
1. Create a [GitHub Account](https://github.com/join).
99
2. Fork the utPLSQL Repository and setup your local Repository.
10-
* Each of the steps below are detailed in the [How to Fork](https://help.github.com/articles/fork-a-repo) article!
10+
* Each of the steps below are detailed in the [how to Fork](https://help.github.com/articles/fork-a-repo) article!
1111
* Clone your Fork to your local machine.
12-
* Configure "upstream" remote to the [master utPLSQL repository](https://github.com/utPLSQL/utPLSQL.git).
13-
* Update the git submodules by issuing command: [git submodule update --remote --merge](http://stackoverflow.com/a/21195182)
14-
3. For each change you want to make:
15-
* Create a new branch for your change.
12+
* Configure "upstream" remote to the [utPLSQL repository](https://github.com/utPLSQL/utPLSQL.git).
13+
3. For each change you want to make:
14+
* 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.
15+
* Create a new branch for your change. We use `feature/feature_name` or `bugfix/fixed_issue_name` to identify branch types.
1616
* Make your change in your new branch.
17-
* Although changes can be made in the master branch, it easier long term if a new branch is used.
18-
* Make sure your change is covered with unit tests and/or is represented in examples
17+
* Make sure your change is covered with unit tests.
1918
* **Verify code compiles and all existing and new unit tests pass.**
20-
* The quickest way to have a Pull Request not be accepted, is to submit code that does not compile or pass tests.
19+
* The quickest way to have a Pull Request not approved, is to submit code that does not compile or pass tests.
2120
* Commit change to your local repository.
22-
* Push change to your remote repository
23-
* Submit a [Pull Request](https://help.github.com/articles/using-pull-requests).
24-
* Note: local and remote branches can be deleted after pull request has been accepted.
25-
26-
**Note:** Getting changes from others requires [Syncing your Local repository](https://help.github.com/articles/syncing-a-fork) with Master utPLSQL repository. This can happen at any time.
27-
21+
* Push change to your remote repository.
22+
* Submit a [Pull Request](https://help.github.com/articles/using-pull-requests) into develop branch.
23+
* Note: local and remote branches can be deleted after pull request has been merged.
2824

2925
## Coding Standards ##
3026

31-
* Snake case will be used. This separates keywords in names with underscores. `execute_test`
32-
* All names will be lower case.
27+
* We use snake case for all identifiers in PLSQL code. This separates keywords in names with underscores. `execute_test`
28+
* All code is lower case.
3329
* Prefixes:
34-
* Arguments to procedures and functions will start with `a_` an Example would be procedure `is_valid(a_owner_name varchar2);`
30+
* Arguments to procedures and functions will start with `a_` an Example would be procedure `is_valid(a_owner_name varchar2)`
3531
* Object types and packages will start with `ut_`
3632
* Local variables `l_`
3733
* Global variables `g_`
@@ -41,27 +37,130 @@ Changes are welcome from all members of the Community.
4137
* varchar2 lengths are set in characters not bytes
4238

4339

44-
## Testing Environment ##
40+
## Configuring local environment ##
41+
42+
Your local environment can be of any flavor (Unix/Linux/Windows/Mac).
43+
At minimum you need to have Oracle database 11.2 XE accessible for the project and SYS account access to install and develop utPLSQL.
44+
45+
We use four different database accounts (users) for development process.
46+
* `ut3_latest_release` - holds latest released version of utPLSQL. This schema holds the testing framework used for self-testing of utPLSQL development.
47+
* `ut3` - holds latest (current) development version of utPLSQL. This is the schema you will be working on.
48+
* `ut3_tester` - holds unit test packages for development of utPLSQL.
49+
* `ut3$user#` - used for testing accessibility to schema names with special characters.
50+
51+
52+
53+
Snippet to get you started with development.
54+
55+
_If you're using Windows, you can run below scripts using `GIT bash` - Windows-based Unix-like command line._
56+
57+
```bash
58+
# clone your fork of utPLSQL
59+
git clone https://github.com/your account/utPLSQL.git utPLSQL
60+
61+
cd utPLSQL
62+
63+
# add main porject repo as upstream
64+
git remote add upstream https://github.com/utPLSQL/utPLSQL.git
65+
66+
# fetch all remote repositories
67+
git fetch --all
68+
69+
# clone utPLSQL master branch from upstream into utPLSQL sub-directory of your project
70+
git clone --depth=1 --branch=master https://github.com/utPLSQL/utPLSQL.git
71+
72+
# download beta version of utPLSQL-cli
73+
curl -Lk -o utPLSQL-cli.zip https://bintray.com/viniciusam/utPLSQL-cli/download_file?file_path=utPLSQL-cli-develop-test3.zip
74+
# unzip utPLSQL-cli and remove the zip file
75+
unzip utPLSQL-cli.zip && chmod -R u+x utPLSQL-cli && rm utPLSQL-cli.zip
76+
77+
```
78+
79+
Refreshing your local repo.
80+
```bash
81+
# fetch all remote repositories
82+
git fetch --all
83+
84+
# remove sub-direcotry containing master branch shallow copy
85+
rm -rf utPLSQL/*
86+
# clone utPLSQL master branch from upstream into utPLSQL sub-directory of your project
87+
git clone --depth=1 --branch=master https://github.com/utPLSQL/utPLSQL.git
88+
89+
rm -rf utPLSQL-cli/*
90+
# download beta version of utPLSQL-cli
91+
curl -Lk -o utPLSQL-cli.zip https://bintray.com/viniciusam/utPLSQL-cli/download_file?file_path=utPLSQL-cli-develop-test3.zip
92+
# unzip utPLSQL-cli and remove the zip file
93+
unzip utPLSQL-cli.zip && chmod -R u+x utPLSQL-cli && rm utPLSQL-cli.zip
94+
95+
```
96+
97+
Cleanup of utPLSQL installation.
98+
```sql
99+
drop user ut3 cascade;
100+
drop user ut3_latest_release cascade;
101+
drop user ut3_tester cascade;
102+
drop user ut3$user# cascade;
103+
104+
begin
105+
for i in (
106+
select decode(owner,'PUBLIC','drop public synonym "','drop synonym "'||owner||'"."')|| synonym_name ||'"' drop_orphaned_synonym from dba_synonyms a
107+
where not exists (select null from dba_objects b where a.table_name=b.object_name and a.table_owner=b.owner )
108+
) loop
109+
execute immediate i.drop_orphaned_synonym;
110+
end loop;
111+
end;
112+
/
113+
```
45114

46-
We are using docker images to test utPLSQL on our Travis CI builds. The following versions of Oracle Database are being used.
115+
Install utPLSQL for development
116+
```bash
117+
export UT3_OWNER=ut3
118+
export UT3_OWNER_PASSWORD=ut3
119+
export UT3_RELEASE_VERSION_SCHEMA=ut3_latest_release
120+
export UT3_TESTER=ut3_tester
121+
export UT3_TESTER_PASSWORD=ut3
122+
export UT3_TABLESPACE=users
123+
export UT3_USER="UT3\$USER#"
124+
export UT3_USER_PASSWORD=ut3
125+
export SQLCLI=sql
126+
export CONNECTION_STR=127.0.0.1:1521/orcl
127+
export ORACLE_PWD=oracle
128+
129+
.travis/install.sh
130+
.travis/install_utplsql_release.sh
131+
.travis/create_additional_grants_for_old_tests.sh
132+
```
133+
134+
Reinstalling utPLSQL development in `ut3` schema.
135+
```bash
136+
cd source
137+
sqlplus sys/oracle@orcl as sysdba <<-SQL
138+
@uninstall ut3
139+
@install ut3
140+
SQL
141+
```
142+
143+
## Build Environment ##
144+
145+
We are using private docker images to test utPLSQL for our Travis CI builds. The following versions of Oracle Database are being used.
47146

48147
* 11g XE R2
49148
* 12c SE R1
50149
* 12c SE R2
51150

52-
These images are based on the official dockerfiles released by Oracle, 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.
151+
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.
152+
You can build your own and use it locally, or push to a private docker repository.
53153

54154
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)
55155

56156
> 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.
57157
58158
> If you are new to Docker, you can start by reading the [Getting Started With Docker](https://docs.docker.com/engine/getstarted/) docs.
59159
60-
### Build Notes ###
61-
* You need to comment out the VOLUME line. This step is required, because volumes are not saved when using `docker commit` command.
62-
63-
* When the build proccess 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.
160+
### Docker Build Notes ###
64161

162+
* You need to comment out the VOLUME line. This step is required, because volumes are not saved when using `docker commit` command.
163+
* 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.
65164
* You can use the --squash experimental docker tag to reduce the image size. Example:
66165
```
67166
docker build --force-rm --no-cache --squash -t oracle/db-prebuilt .
@@ -75,7 +174,7 @@ Variable | Description
75174

76175
### SQLCL ###
77176

78-
Our build configurarion 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.
177+
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.
79178

80179
Variable | Description
81180
---------|------------

0 commit comments

Comments
 (0)