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

Skip to content

Commit 88127d8

Browse files
jgebaljgebal
committed
Final updates to CONTRIBUTING.md
1 parent d4e2891 commit 88127d8

1 file changed

Lines changed: 56 additions & 18 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 56 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
1-
## How to contribute ##
1+
# How to contribute
22

33
The following are the guidelines everyone should use to contribute to utPLSQL.
44
Changes are welcome from all members of the Community.
55

6-
## Getting Started ##
6+
# Getting Started
77

88
1. Create a [GitHub Account](https://github.com/join).
99
2. Fork the utPLSQL Repository and setup your local Repository.
@@ -22,7 +22,7 @@ Changes are welcome from all members of the Community.
2222
* Submit a [Pull Request](https://help.github.com/articles/using-pull-requests) into develop branch.
2323
* Note: local and remote branches can be deleted after pull request has been merged.
2424

25-
## Coding Standards ##
25+
# Coding Standards
2626

2727
* We use snake case for all identifiers in PLSQL code. This separates keywords in names with underscores. `execute_test`
2828
* All code is lower case.
@@ -37,7 +37,7 @@ Changes are welcome from all members of the Community.
3737
* varchar2 lengths are set in characters not bytes
3838

3939

40-
## Configuring local environment ##
40+
# Configuring local environment
4141

4242
Your local environment can be of any flavor (Unix/Linux/Windows/Mac).
4343
At minimum you need to have Oracle database 11.2 XE accessible for the project and SYS account access to install and develop utPLSQL.
@@ -50,7 +50,9 @@ We use four different database accounts (users) for development process.
5050

5151

5252

53-
### To get started with development, follow the below steps.
53+
## Get started with development
54+
55+
To get started with development, follow the below steps.
5456

5557
_If you're using Windows, run the shell scripts using `GIT bash` - Windows-based bash command line._
5658

@@ -68,7 +70,7 @@ git remote add upstream https://github.com/utPLSQL/utPLSQL.git
6870
git fetch --all
6971
```
7072

71-
**Prepare environment script**
73+
### Prepare environment script
7274

7375
Copy the environment variables template `development/template.env.sh` to `development/env.sh`
7476
```bash
@@ -84,19 +86,22 @@ export CONNECTION_STR=127.0.0.1:1521/xe # Adjust the connect string
8486
export ORACLE_PWD=oracle # Adjust your local SYS password
8587
```
8688

87-
**Download utPLSQL release sources and utplsq-cli**
89+
### Download utPLSQL release sources and utplsq-cli
8890

89-
_The below script is fetching latest release version from utPLSQL repository. Latest release version is used for self-testing._
91+
The below script is fetching latest release version from utPLSQL repository. Latest release version is used for self-testing.
9092
```bash
9193
development/refresh_sources.sh
9294
```
9395

94-
**Setup local database for utPLSQL development**
96+
### Setup local database for utPLSQL development
97+
9598
```bash
9699
development/install.sh
97100
```
98101

99-
That's it! You now have the following:
102+
### That's it
103+
104+
You now have the following:
100105
- sources from `develop` branch of your fork of utPLSQL repository in `utPLSQL/ut3_latest_release` directory
101106
- sources from `master` branch of utPLSQL/utPLSQL repository in `utPLSQL/ut3_latest_release` directory
102107
- binaries of `utplsql-cli` in `utPLSQL/utPLSQL-cli` directory
@@ -106,27 +111,60 @@ That's it! You now have the following:
106111

107112
At any time, if you need to refresh your database, the below scripts might be helpful.
108113

109-
### Cleanup of utPLSQL installation in local database
114+
## Running unit tests
115+
116+
Currently we use two forms of unit tests in our CI build:
117+
- sql scripts as unit tests in the `old_tests` directory
118+
- utPLSQL v3 unit tests in the `test` directory
119+
120+
Before you push any changes and create a pull request to the utPLSQL project repository, make sure that all of the tests are executing successfully in your local environment.
121+
122+
Every new functionality needs to be documented by unit tests that cover both happy-path scenarios as well as edge-cases and exception paths.
123+
124+
> **Important notice:**
125+
> We do our best to keep utPLSQL covered with unit tests.
126+
> Lack of sufficient unit testing is a perfect reason for PR to be rejected.
127+
128+
To suite of legacy unit tests execute:
129+
```bash
130+
development/env.sh
131+
old_tests/runAll.sh
132+
```
133+
To run a full suite of unit tests execute:
134+
```bash
135+
development/env.sh
136+
test/install_and_run_tests.sh
137+
```
138+
139+
You can review the results of tests as well as see information about code coverage in `./old_tests/coverage.html, ./coverage.html` files.
140+
141+
142+
## Cleanup of utPLSQL installation in local database
143+
110144
```bash
111145
development/cleanup.sh
112146
```
113147

114-
### Reinstalling utPLSQL development in `ut3` schema
148+
## Reinstalling utPLSQL development in `ut3` schema
149+
115150
```bash
116151
development/refresh_ut3.sh
117152
```
118153

119-
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.
154+
## Refreshing after release
155+
156+
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.
157+
120158

121-
## Modules ##
159+
## Modules
122160

123161
Below diagram gives a high-level overview of utPLSQL v3 modules and their dependencies.
124162
Dependencies to `ut_util` are not shown as most of modules are depending on it.
125163

126164
![utPLSQL V3 Modules](development/utPSLQLv3-modules.png)
127165

128166

129-
## Build Environment ##
167+
## Build Environment
130168

131169
We are using private docker images to test utPLSQL for our Travis CI builds. The following versions of Oracle Database are being used.
132170

@@ -143,7 +181,7 @@ The build steps are simple if you already have some experience using Docker. You
143181
144182
> If you are new to Docker, you can start by reading the [Getting Started With Docker](https://docs.docker.com/engine/getstarted/) docs.
145183
146-
### Docker Build Notes ###
184+
### Docker Build Notes
147185

148186
* You need to comment out the VOLUME line. This step is required, because volumes are not saved when using `docker commit` command.
149187
* 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.
@@ -158,7 +196,7 @@ Variable | Description
158196
---------|------------
159197
**DOCKER_USER**<br />**DOCKER_PASSWORD** | _Your Docker Hub website credentials. They will be used to pull the private database images._
160198

161-
### SQLCL ###
199+
### SQLCL
162200

163201
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.
164202

@@ -167,7 +205,7 @@ Variable | Description
167205
**ORACLE_OTN_USER<br />ORACLE_OTN_PASSWORD** | _Your Oracle website credentials. They will be used to download SQLCL._
168206

169207

170-
## New to GIT ##
208+
## New to GIT
171209

172210
If you are new to GIT here are some links to help you with understanding how it works.
173211

0 commit comments

Comments
 (0)