Merge pull request #349 from john-otoole/documentation-fixes

Pazus · web-flow · commit cb4fa1b58551 · 2017-06-12T09:52:49.000+03:00
Minor updates to the MD documentation files
diff --git a/development/readme.md b/development/readme.md
@@ -1,6 +1,6 @@
 # Build Folder
 
- Contains the build scripts that can be run locally on a developers machine to build run and test utPLSQL.  
+ Contains the build scripts that can be run locally on a developer's machine to build, run and test utPLSQL.  
 
- These scripts are also used by Jenkins Continuous integration server to check each pull request before it is merged.
+ These scripts are also used by the Jenkins Continuous Integration server to check each pull request before it is merged.
 
diff --git a/development/releasing.md b/development/releasing.md
@@ -1,11 +1,11 @@
-Release process is automated in following way:
-1) with every build, the build process on travis updatse files with appropriate version number before deployment into db.
+The release process is automated in the following way:
+1) With every build, the build process on Travis updates files with an appropriate version number before deployment into the database.
    This is to confirm that the update of versions works properly.
-2) when build is executed on a branch named `release/v1.2.3-something` then additional steps are taken:
-    - project version in files: `sonar-project.properties`, `VERSION` is updated from the version number derived from release branch
-    - changes on those two files are committed and and pushed - this should happen only once, when the release branch is initially created on the main repo
+2) When a build is executed on a branch named `release/v1.2.3-something` then additional steps are taken:
+    - the project version in files: `sonar-project.properties`, `VERSION` is updated from the version number derived from the release branch
+    - changes to those two files are committed and pushed - this should happen only once, when the release branch is initially created on the main repo
 3) To create a release, just create a tag on the code to be released. The tag name must match the regex pattern: `^v[0-9]+\.[0-9]+\.[0-9]+.*$`
    - When a tag build is executed, the documentation is built and files are uploaded to the tag.
    - The version number is derived from the tag name.
-4) Release version do not provide access to unversioned source files (the default zip file from github is empty). 
-   The sources for release are provided in separate zip files delivered from travis build process.
+4) The release version does not provide access to unversioned source files (the default zip file from GitHub is empty). 
+   The sources for release are provided in separate zip files delivered from the Travis build process.
diff --git a/docs/about/CONTRIBUTING.md b/docs/about/CONTRIBUTING.md
@@ -1,6 +1,6 @@
 ## How to contribute ##
 
-The following are the guidelines, everyone should use to contribute to utPLSQL.  
+The following are the guidelines everyone should use to contribute to utPLSQL.  
 Changes are welcome from all members of the Community. 
 
 ## Getting Started ##
diff --git a/docs/about/support.md b/docs/about/support.md
@@ -1,4 +1,4 @@
 # How to get support
 
-- Feel free post questions, bugs or issues in the [issues area of GitHub](https://github.com/utPLSQL/utPLSQL/issues).
-- Join developers the [utPLSQL team](http://utplsql-slack-invite.herokuapp.com) on [Slack](https://slack.com/)
+- Feel free to post questions, bugs or issues in the [issues area of GitHub](https://github.com/utPLSQL/utPLSQL/issues)
+- Join developers at the [utPLSQL team](http://utplsql-slack-invite.herokuapp.com) on [Slack](https://slack.com/)
diff --git a/docs/userguide/annotations.md b/docs/userguide/annotations.md
@@ -17,9 +17,9 @@ Procedure annotations are defined right before the procedure they reference, no
 
 If a package specification contains `%suite` annotation, it is treated as a test package and processed by the framework.
 
-Some annotations accept parameters like `%suite`, `%test` `%displayname`. The parameters for annotations need to be placed in brackets. Values for parameters should be provided without any quotation marks.
+Some annotations accept parameters like `%suite`, `%test` and `%displayname`. The parameters for annotations need to be placed in brackets. Values for parameters should be provided without any quotation marks.
 
-# <a name="example"></a>Example of annotated test package
+# <a name="example"></a>Example of an annotated test package
 
 ```sql
 create or replace package test_pkg is
@@ -87,9 +87,9 @@ end test_pkg;
 
 It is very likely that the application for which you are going to introduce tests consists of many different packages or procedures/functions. Usually procedures can be logically grouped inside a package, there also might be several logical groups of procedure in a single package or even packages themselves might relate to a common module.
 
-Lets say you have a complex insurance application the operates with policies, claims and payments. The payment module contains several packages for payment recognition, charging, planning etc. The payment recognition module among others contains a complex `recognize_payment` procedure that associates received money to the policies.
+Let's say you have a complex insurance application that deals with policies, claims and payments. The payment module contains several packages for payment recognition, charging, planning etc. The payment recognition module among others contains a complex `recognize_payment` procedure that associates received money to the policies.
 
-If you want to create tests for your application it is recommended to structure your tests similarly to the logical structure of you application. So you end up with something like:
+If you want to create tests for your application it is recommended to structure your tests similarly to the logical structure of your application. So you end up with something like:
 * Integration tests
   *   Policy tests
   *   Claim tests
@@ -98,7 +98,7 @@ If you want to create tests for your application it is recommended to structure
     * Payments set off
     * Payouts 
     
-The `%suitepath` annotation is used for such grouping. Even though test packages are defined in a flat structure the `%suitepath` is used by the framework to form a hierarchical structure of them. Your payments recognition test package might look like:
+The `%suitepath` annotation is used for such grouping. Even though test packages are defined in a flat structure the `%suitepath` is used by the framework to form them into a hierarchical structure. Your payments recognition test package might look like:
 
 ```sql
 create or replace package test_payment_recognition as
@@ -136,10 +136,10 @@ create or replace package test_payment_set_off as
 end test_payment_set_off;
 ```
 
-When you execute tests for your application, the framework constructs test suite for each test package. Then in combines suites into grouping suites by the `%suitepath` annotation value so that the fully qualified path to the `recognize_by_num` procedure is `USER:payments.test_payment_recognition.test_recognize_by_num`. If any of its expectations fails then the test is marked as failed, also the `test_payment_recognition` suite, the parent suite `payments` and the whole run is marked as failed.
-The test report indicates which expectation has failed on the payments module. The payments recognition submodule is causing the failure as `recognize_by_num` has is not meeting the expectations of the test. Grouping tests into modules and submodules using the `%suitepath` annotation allows you to logically organize your projects flat structure of packages int functional groups. 
+When you execute tests for your application, the framework constructs a test suite for each test package. Then it combines suites into grouping suites by the `%suitepath` annotation value so that the fully qualified path to the `recognize_by_num` procedure is `USER:payments.test_payment_recognition.test_recognize_by_num`. If any of its expectations fails then the test is marked as failed, also the `test_payment_recognition` suite, the parent suite `payments` and the whole run is marked as failed.
+The test report indicates which expectation has failed on the payments module. The payments recognition submodule is causing the failure as `recognize_by_num` has not met the expectations of the test. Grouping tests into modules and submodules using the `%suitepath` annotation allows you to logically organize your project's flat structure of packages into functional groups. 
 
-Additional advantage of such grouping is the fact that every element level of the grouping can be an actual unit test package containing module level common setup for all of the submodules. So in addition to the packages mentioned above you could have following package.
+An additional advantage of such grouping is the fact that every element level of the grouping can be an actual unit test package containing a common module level setup for all of the submodules. So in addition to the packages mentioned above you could have the following package.
 ```sql
 create or replace package payments as
 
@@ -153,38 +153,38 @@ create or replace package payments as
 
 end payments;
 ```
-A `%suitepath` can be provided in tree ways:
-* schema - execute all test in the schema
-* [schema]:suite1[.suite2][.suite3]...[.procedure] - execute all tests in all suites from suite1[.suite2][.suite3]...[.procedure] path. If schema is not provided, then current schema is used. Example: `:all.rooms_tests`.
-* [schema.]package[.procedure] - execute all tests in the test package provided. The whole hierarchy of suites in the schema is build before, all before/after hooks of partn suites for th provided suite package are executed as well. Example: `tests.test_contact.test_last_name_validator` or simply `test_contact.test_last_name_validator` if `tests` is the current schema.
+A `%suitepath` can be provided in three ways:
+* schema - execute all tests in the schema
+* [schema]:suite1[.suite2][.suite3]...[.procedure] - execute all tests in all suites from suite1[.suite2][.suite3]...[.procedure] path. If schema is not provided, then the current schema is used. Example: `:all.rooms_tests`
+* [schema.]package[.procedure] - execute all tests in the specified test package. The whole hierarchy of suites in the schema is built before all before/after hooks or part suites for the provided suite package are executed as well. Example: `tests.test_contact.test_last_name_validator` or simply `test_contact.test_last_name_validator` if `tests` is the current schema.
 
 # Using automatic rollbacks in tests
 
-By default, changes performed by every setup, cleanup and test procedure is isolated using savepoint.
-This solution is suitable for use-cases, where the code that is getting tested as well as the unit tests themselves do not use transaction control (commit/rollback) or DDL commands.
+By default, changes performed by every setup, cleanup and test procedure are isolated by savepoints.
+This solution is suitable for use-cases where the code that is getting tested as well as the unit tests themselves do not use transaction control (commit/rollback) or DDL commands.
 
 In general, your unit tests should not use transaction control as long as the code you are testing is not using it too.
-Keeping the transactions uncommitted allows your changes to be isolated and the execution of tests is not impacting others that might be using a shared development database.
+Keeping the transactions uncommitted allows your changes to be isolated and the execution of tests does not impact others who might be using a shared development database.
 
-If you are in situation, where the code you are testing, is using transaction control (common case with ETL code), then your tests probably should not use the default automatic transaction control.
-In that case use the annotation `-- %rollback(manual)` on the suite level to disable automatic transaction control for entire suite.
+If you are in a situation where the code you are testing uses transaction control (common case with ETL code), then your tests probably should not use the default automatic transaction control.
+In that case use the annotation `-- %rollback(manual)` on the suite level to disable automatic transaction control for the entire suite.
 If you are using nested suites, you need to make sure that the entire suite all the way to the root is using manual transaction control.
 
 It is possible with utPLSQL to change the transaction control on individual suites or tests that are part of complex suite.
-It is strongly recommended not to have mixed transaction control in suite.
+It is strongly recommended not to have mixed transaction control in a suite.
 Mixed transaction control settings will not work properly when your suites are using shared setup/cleanup with beforeall, afterall, beforeeach or aftereach annotations.
-Your suite will most probably fail with error or warning on execution. Some of the automatic rollbacks will most probably fail to execute depending on the configuration you have.
+Your suite will most likely fail with error or warning on execution. Some of the automatic rollbacks will probably fail to execute depending on the configuration you have.
 
-In some cases it is needed to perform DDL as part of setup or cleanup for the tests. 
-It is recommended to move such DDL statements to a procedure with `pragma autonomous_transaction` to eliminate implicit commit in the main session that is executing all your tests.
-Doing so, allows your test to use automatic transaction control of the framework and release you from the burden of manual cleanup of data that was created or modified by test execution.
+In some cases it is necessary to perform DDL as part of setup or cleanup for the tests. 
+It is recommended to move such DDL statements to a procedure with `pragma autonomous_transaction` to eliminate implicit commits in the main session that is executing all your tests.
+Doing so allows your tests to use the framework's automatic transaction control and releases you from the burden of manual cleanup of data that was created or modified by test execution.
 
-When you are running test of code that is performing an explicit or implicit commit, you may set the test procedure to run in autonomous transaction with `pragma autonomous_transaction`.
-Keep in mind, that when your tests runs in autonomous transaction it will not see the data prepared in setup procedure unless the setup procedure committed the changes. 
+When you are testing code that performs explicit or implicit commits, you may set the test procedure to run as an autonomous transaction with `pragma autonomous_transaction`.
+Keep in mind that when your tests runs in autonomous transaction it will not see the data prepared in setup procedure unless the setup procedure committed the changes. 
 
 # Order of execution
 
-When processing the test suite `test_pkg` defined in [Example of annotated test package](#example), the execution will be done in the following order.
+When processing the test suite `test_pkg` defined in [Example of annotated test package](#example), the order of execution will be as follows.
 
 ```
   create a savepoint 'beforeall'
diff --git a/docs/userguide/best-practices.md b/docs/userguide/best-practices.md
@@ -1,13 +1,13 @@
 # Best Practices
 
-The following are best practices we as utPLSQL have learned about PL/SQL and Unit Testing. 
+The following are best practices we at utPLSQL have learned about PL/SQL and Unit Testing. 
 
 ## Test Isolation and Dependency
 
  - Tests should not depend on a specific order to run 
  - Tests should not depend on other tests to execute
- - Tests should not depend on specific database state, they should setup the expected state before run
- - Tests should keep environment unchanged post execution
+ - Tests should not depend on specific database state, they should setup the expected state before being run
+ - Tests should keep the environment unchanged post execution
 
 
 ## Writing tests
@@ -21,26 +21,26 @@ The following are best practices we as utPLSQL have learned about PL/SQL and Uni
  - Each tested procedure/function/trigger (code block) should have more than one test
  - Each test should check only one behavior (one requirement) of the code block under test
  - Tests should be maintained as thoroughly as production code
- - Every test needs to be build so that it can fail, tests that do not fail when needed are useless  
+ - Every test needs to be built so that it can fail, tests that do not fail when needed are useless  
   
 ## Gaining value from the tests
  
- - Tests are only valuable if they are executed frequently, ideally - with every change to the project code
- - Tests need to run very fast, the slower the tests - the longer you wait. Build tests with performance in mind (do you need to have 10k rows to run the tests?)
- - Tests, that are not executed frequently enough get rotten pretty fast and bring burden instead of value. Maintain tests as you maintain code.
- - Tests that are failing, need to be addressed immediately. How can you trust tour tests when 139 of 1000 tests are failing for a month? Will you be able to see each time that it is still the same 139 tests?  
+ - Tests are only valuable if they are executed frequently; ideally with every change to the project code
+ - Tests need to run very fast; the slower the tests, the longer you wait. Build tests with performance in mind (do you really need to have 10k rows to run the tests?)
+ - Tests that are executed infrequently can quickly become stale and end up adding overhead rather than value. Maintain tests as you would maintain code.
+ - Tests that are failing need to be addressed immediately. How can you trust your tests when 139 of 1000 tests are failing for a month? Will you recognise each time that it is still the same 139 tests?  
 
 ## Tests are not for production
 
- Tests generate will generate and operate on fake data. They might insert/update and delete data. You don't want tests to run on production database and touch on real-life data.
+ Tests will generate and operate on fake data. They might insert, update and delete data. You don't want tests to run on a production database and affect real life data.
 
-## Tests and their relationship to code under test.
- -  Code under test and tests should be in separate packages. This is fundamental separation of responsibilities.
- -  Test code commonly will be in the same schema as the tested code. This removes the need to manage privileges for the tests. 
+## Tests and their relationship to code under test
+ -  Tests and the code under test should be in separate packages. This is a fundamental separation of responsibilities.
+ -  It is common for test code to be in the same schema as the tested code. This removes the need to manage privileges for the tests. 
 
 ## Version Control
 
 Use a version control system for your code. 
 Don't just trust the database for code storage.
 This includes both the code under test, and the unit tests you develop as well.
-Treat database as target, destination for your code not as a source of it.
+Treat the database as a target/destination for your code, not as a source of it.
diff --git a/docs/userguide/running-unit-tests.md b/docs/userguide/running-unit-tests.md
diff --git a/docs/userguide/upgrade.md b/docs/userguide/upgrade.md
diff --git a/readme.md b/readme.md
