Merge pull request #2 from Trivadis/feature/21c

Feature/21c

FAQ.md

@@ -10,7 +10,7 @@ See the [release information](https://github.com/Trivadis/plsql-cop-sonar/releas
 
 ## What are the licensing terms?
 
-The preview/trial version of PL/SQL Cop for SonarQube is licensed under the Creative Commons Attribution-NonCommercial-NoDerivs 3.0 Unported License. You may obtain a copy of the License at https://creativecommons.org/licenses/by-nc-nd/3.0/.
+The preview/trial version of db* CODECOP for SonarQube is licensed under the Creative Commons Attribution-NonCommercial-NoDerivs 3.0 Unported License. You may obtain a copy of the License at https://creativecommons.org/licenses/by-nc-nd/3.0/.
 
 ![CC-BY_NC-ND](images/CC-BY-NC-ND.png)
 

README.md

@@ -1,66 +1,150 @@
-# PL/SQL Cop for SonarQube
+# db\* CODECOP for SonarQube
 
 ## Introduction
 
-PL/SQL Cop for SonarQube is a plugin for [SonarQube](http://www.sonarqube.org/). The plugin analyses SQL and PL/SQL code and calculates various metrics and checks the code for compliance of the [Trivadis PL/SQL & SQL Coding Guidelines Version 3.6](https://trivadis.github.io/plsql-and-sql-coding-guidelines/v3.6/). Behind the scenes the plugin calls the [PL/SQL Cop command line](https://github.com/Trivadis/plsql-cop-cli) utility for the static code analysis.
+db\* CODECOP for SonarQube is a plugin for [SonarQube](http://www.sonarqube.org/). The plugin analyses SQL and PL/SQL code and calculates various metrics and checks the code for compliance of the [Trivadis PL/SQL & SQL Coding Guidelines Version 4.0](https://trivadis.github.io/plsql-and-sql-coding-guidelines/v4.0/). Behind the scenes the plugin calls the [db\* CODECOP command line](https://github.com/Trivadis/plsql-cop-cli) utility for the static code analysis.
 
-A static code analysis is typically initiated as part of an continuous integration setup, e.g. at the end of a Jenkins or Hudson build job. SonarQube stores the result of the analysis in a relational database. Supported are HSQLDB, PostgreSQL, MySQL, Microsoft SQL Server and Oracle Database, of course.
+A static code analysis is typically initiated as part of an continuous integration setup, e.g. at the end of a Jenkins or Hudson build job. SonarQube stores the result of the analysis in a relational database. Supported are PostgreSQL, Microsoft SQL Server and Oracle Database. For evaluation purposes, the embedded H2 database can also be used.
 
-Since every analysis is stored as a snapshot in the SonarQube repository the improvement or the decrease of the code quality may be monitored very well. Use SonarQube and the PL/SQL Cop plugin if you care about your PL/SQL code quality.
+Since every analysis is stored as a snapshot in the SonarQube repository the improvement or the decrease of the code quality may be monitored very well. Use SonarQube and the db\* CODECOP plugin if you care about your PL/SQL code quality.
 
 ## Examples
 
-Setup a build job with a standalone SonarQube analysis at the end of the job. Here’s an example within a Jenkins build job:
-
-![Jenkins Build Plan](images/jenkins_1.png)
-
-Important are the analysis properties. The mandatory ones are sonar.projectKey, sonar.projectName, sonar.projectVersion and sonar.sources. You may defined them as shown above or within a sonar.properties file in the source folder. See the [SonarQube documentation](http://docs.sonarqube.org/display/SONAR/Analysis+Parameters) for more information.
-
-The build job is typically started after a change in the software configuration system such as GIT, SVN or CVS or other relevant events. You may even trigger the build manually. The log of such a build job looks as follows:
-
-![Jenkins Console Output 1](images/jenkins_2.png)
-![Jenkins Console Output 2](images/jenkins_3.png)
-
-At the bottom of a build log you find a link to the SonarQube project dashboard. Click on it and the following project dashboard is shown:
+### Run Code Analysis via SonarScanner
+
+You start an analysis from the command line as follows (see [docs](https://docs.sonarqube.org/latest/analysis/scan/sonarscanner/) for more information):
+
+```
+sonar-scanner -Dsonar.projectKey="sample"
+```
+
+Here's an excerpt of the output:
+
+```
+INFO: Scanner configuration file: /usr/local/opt/sonar-scanner/conf/sonar-scanner.properties
+INFO: Project root configuration file: NONE
+INFO: SonarQube Scanner 4.1.0.1829
+...
+INFO: Project configuration:
+INFO: 115 files indexed
+INFO: Quality profile for plsql: db* CODECOP
+INFO: ------------- Run sensors on module sample
+INFO: JavaScript/TypeScript frontend is enabled
+INFO: Define db* CODECOP PlugIn (Secondary)
+INFO: Load metrics repository
+INFO: Load metrics repository (done) | time=36ms
+INFO: PlSQL COP Sensor initializing
+INFO: Instantiate class: com.trivadis.sonar.plugin.TrivadisGuidelines3ValidatorConfig
+INFO: Sensor CSS Rules [cssfamily]
+INFO: No CSS, PHP, HTML or VueJS files are found in the project. CSS analysis is skipped.
+INFO: Sensor CSS Rules [cssfamily] (done) | time=1ms
+INFO: Sensor PL/SQL Sensor [plsql]
+INFO: 115 source files to be analyzed
+INFO: Load project repositories
+INFO: Load project repositories (done) | time=10ms
+...
+INFO: Analysis report generated in 149ms, dir size=603 KB
+INFO: Analysis report compressed in 1101ms, zip size=264 KB
+INFO: Analysis report uploaded in 1858ms
+INFO: ANALYSIS SUCCESSFUL, you can browse http://localhost:9000/dashboard?id=sample
+INFO: Note that you will be able to access the updated dashboard once the server has processed the submitted analysis report
+INFO: More about the report processing at http://localhost:9000/api/ce/task?id=AXiSv3IJVMRTx5sCSVMo
+INFO: Analysis total time: 27.088 s
+INFO: ------------------------------------------------------------------------
+INFO: EXECUTION SUCCESS
+INFO: ------------------------------------------------------------------------
+INFO: Total time: 28.961s
+INFO: Final Memory: 40M/144M
+INFO: ------------------------------------------------------------------------
+```
+
+At the end of the run an URL to the scanner result is provided.
+
+### Run Code Analyis with CI Environments
+
+You can call the SonarScanner also from Grade, .NET projects, Maven, Ant, Jenkins, etc. The mechanisms are the same as with the command line tool. In the end the analyis report is uploaded to SonarQube.
+
+See [SonarScanner](https://docs.sonarqube.org/latest/analysis/scan/sonarscanner/) for more information.
+
+### View Code Analysis Result in SonarQube
+
+SonarQube gathers the code analysis reports per project. Here are the results of the previous analysis.
 
 ![SonarQube Dashboard](images/sonar_1.png)
 
-You see that 2 blocker issues have been found in the guideline project. Click on “2” to drill down to the blocker issues.
+Under `Issues` the following `Blocker` are shown:
 
 ![SonarQube Issues](images/sonar_2.png)
 
-Click on the arrow on the right side of an issue to drill down to the source code.
+By clicking on the redish box you can drill down to the source code.
 
 ![SonarQube Issues in Source](images/sonar_3.png)
 
-Click on the three dots after the issue text to get more information about the violated guideline.
+When clicking on `Why is this an issue?` the complete rule is shown in simlar way as in the [Trivadis PL/SQL & SQL Coding Guidelines v4.0](https://trivadis.github.io/plsql-and-sql-coding-guidelines/v4.0/4-language-usage/5-exception-handling/g-5030/).
 
 ![SonarQube Guideline Details](images/sonar_4.png)
 
-There are a lot more analysis available in [SonarQube](http://docs.sonarqube.org/display/SONAR/Installing+a+Plugin). Get your copy of [PL/SQL Cop](https://github.com/Trivadis/plsql-cop-cli/releases) and [PL/SQL Cop for SonarQube](https://github.com/Trivadis/plsql-cop-sonar/releases) now.
+See [SonarQube documentation](https://docs.sonarqube.org/latest/) for more information.
 
 ## Installation
 
-Copy the downloaded sonar-plsql-cop-plugin-x.x.x.x.jar file into the extensions/plugins folder of your SonarQube installation and restart the [SonarQube](http://docs.sonarqube.org/display/SONAR/Installing+a+Plugin) server. Login as admin, click on “Settings” in the main menu bar and configure the “Trivadis PL/SQL Cop” section as shown below
+db\* CODECOP provides two types of plugins. 
+
+- [Standalone Plugin](#standalone-plugin)
+
+  Use this plugin if db\* CODECOP is the only SonarQube plugin that processes SQL and PL/SQL related files.
+
+- [Secondary Plugin](#secondary-plugin)
+
+  Use this plugin if you plan to use another PL/SQL SonarQube plugin together with db\* CODECOP. 
+
+  By default, SonarQube allows only one plugin to process a given file extension. Therefore, it is not possible to use the standalone plugin in this scenario.
+
+  The secondary plugin allows you to configure another plugin as the primary plugin. The primary plugin is the one that is responsible to manage the associated file extensions.
+
+  The secondary plugin was tested with the following plugins:
+
+    - [SonarPLSQL](https://docs.sonarqube.org/latest/analysis/languages/plsql/) (default)
+    - [ZPA](https://felipezorzo.com.br/zpa/)
+
+  However, it should be possible to configure other primary plugins.
+
+### Standalone Plugin
+
+Download the `sonar-plsql-cop-standalone-x.x.x.jar` from [releases](https://github.com/Trivadis/plsql-cop-sonar/releases). Then copy it to the `extensions/plugins` folder of your SonarQube installation and restart the [SonarQube](http://docs.sonarqube.org/display/SONAR/Installing+a+Plugin) server. Login as admin, click on `Administration` in the main menu bar and configure the `db* CODECOP` section as shown below.
+
+![db\* CODECOP standalone plugin configuration in SonarQube](images/sonar_standalone_config.png)
+
+The `File suffix filter` associates file extensions to the db\* CODECOP plugin.
+
+Paste the content of the `.lic` file you've got from your Trivadis representative into the `license file` field.
+
+The `Validator Config class` defines the validator with its rule and profile definition for SonarQube. By default, the following classes are available:
+
+Validator Config class | Description
+--- | ---
+com.trivadis.sonar.plugin.TrivadisGuidelines3ValidatorConfig | Rules based on Trivadis PL/SQL & SQL Codeing Guidelines 4.0. This is the default.
+com.trivadis.sonar.plugin.TrivadisGuidelines2ValidatorConfig | Rules based Trivadis PL/SQL & SQL Codeing Guidelines 4.0, but only those that were available in v2.0 using two digits per rule.
+com.trivadis.sonar.plugin.EmptyPLSQLValidatorConfig | Minimal rule set (G-0000, E-000x), e.g. to calculate metrics only.
+
+You can create and configure custom validator config classes. See [this GitHub project](https://github.com/Trivadis/plsql-cop-validators) for more information. 
+
+### Secondary Plugin
 
-![PL/SQL Cop configuration in SonarQube](images/sonar_5.png)
+Download the `sonar-plsql-cop-secondary-x.x.x.jar` from [releases](https://github.com/Trivadis/plsql-cop-sonar/releases). Then copy it to the `extensions/plugins` folder of your SonarQube installation and restart the [SonarQube](http://docs.sonarqube.org/display/SONAR/Installing+a+Plugin) server. Login as admin, click on `Administration` in the main menu bar and configure the `db* CODECOP` section as shown below.
 
-Press “Save Trivadis PL/SQL Cop Settings” to the configuration.
+![db\* CODECOP secondary plugin configuration in SonarQube](images/sonar_secondary_config.png)
 
-The path to the PL/SQL Cop command line utility and the license file must be valid for the machine doing the analysis with [SonarQube Scanner](https://docs.sonarqube.org/display/SCAN/Analyzing+with+SonarQube+Scanner). If you are using Jenkins then PL/SQL Cop command line utility must be installed on every Jenkins node.
+The `Language Key` identifies the primary plugin which manages the file associations and is responsible for some common code analysis tasks. Enter `plsql` for SonarPLSQL or `plsqlopen` for ZPA.
 
-## Releases
+The meaning of `License file` and `Validator Config class` is identical to the standalone plugin. 
 
-It’s important to note, that each version of PL/SQL Cop for SonarQube requires specific versions of SonarQube. Updates are considered only for SonarQube LTS (long term support) versions.
+## Compatibiltiy
 
-| Plugin Version | Supported SonarQube Version | Required CLI Version |
-| :------------: | :-------------------------: | :------------------: |
-| [4.5.0.1](https://github.com/Trivadis/plsql-cop-sonar/releases/tag/v4.5.0.1) | 4.5 LTS - 5.1.2 | 2.3.x  |
-| [5.6.0.2](https://github.com/Trivadis/plsql-cop-sonar/releases/tag/v5.6.0.2) | 5.6 LTS - 6.6 | 2.3.x |
-| [6.7.0.4](https://github.com/Trivadis/plsql-cop-sonar/releases/tag/v6.7.0.4) | 6.7 LTS - 7.6 | 2.3.x|
-| [7.9.0.1](https://github.com/Trivadis/plsql-cop-sonar/releases/tag/v7.9.0.1) | 7.9 LTS - 8.0 | 2.3.x |
+The current plugins are compatible with all on-premises SonarQube editions (Community, Developer, Enterprise and Data Center).
 
-You find all releases and release information [here](https://github.com/Trivadis/plsql-cop-sonar/releases).
+- Minumum SonarQube version: 7.9
+- Latest SonarQube version tested: 8.7.1
 
 ## Issues
 Please file your bug reports, enhancement requests, questions and other support requests within [Github's issue tracker](https://help.github.com/articles/about-issues/).
@@ -76,11 +160,11 @@ see [Frequently Asked Questions](FAQ.md).
 
 ## Further Information
 
-Please find further information about PL/SQL Cop on the [Trivadis](https://www.trivadis.com/en/plsql-cop) website.
+Please find further information about db\* CODECOP on the [Trivadis](https://www.trivadis.com/en/plsql-cop) website.
 
 ## License
 
-The preview/trial version of PL/SQL Cop for SonarQube is licensed under the Creative Commons Attribution-NonCommercial-NoDerivs 3.0 Unported License. You may obtain a copy of the License at https://creativecommons.org/licenses/by-nc-nd/3.0/.
+The preview/trial version of db\* CODECOP for SonarQube is licensed under the Creative Commons Attribution-NonCommercial-NoDerivs 3.0 Unported License. You may obtain a copy of the License at https://creativecommons.org/licenses/by-nc-nd/3.0/.
 
 ![CC-BY_NC-ND](images/CC-BY-NC-ND.png)