Starter pack

Basic Explanations

In order to develop a Sonarqube Plugin in Open source for Creedengo, the following basics should have been understood:

Sonarqube Plugin

Here is the official documentation to understand how to develop a sonar plugin: https://docs.sonarqube.org/latest/extend/developing-plugin/ However, we are going to help you more specifically for creedengo project in the following sections.

How a SonarQube plugin works

Code is parsed to be transformed as an AST (Abstract Syntax Tree). This AST will allow you to access one or more nodes of your code. For example, you’ll be able to access all of the for loops, to explore content etc.

To better understand AST structure, you can use the AST Explorer and select the language of the code you want to explore.

The JavaScript Sonar plugin works differently because it doesn’t parse the code to transform it into an AST itself, it uses the ESLint engine which does the parsing by itself (More information here). The good part is that it means that all Creedengo JavaScript rules are made available both to Sonar and to ESLint through a Creedengo ESLint plugin.

GitFlow

What is GitFlow and how it works: https://medium.com/android-news/gitflow-with-github-c675aa4f606a

How to develop in open-source mode

Useful links

Creedengo’s GitHub repos

See all Green Code Initiative’s repos here: here

Some rules reference

Initialize local development

This section will help you to install and configure your first environment to develop with us!!!

We advise you to use Sdkman.io to manage the versions of your tools, locally. This tool will install different versions as you want.

Requirements

Method 1 - Automatic check (default method)

  1. In the Creedengo commons repository,go to tools/check_requirements directory.

  2. Execute the script verification: ./check_requirements.sh on macOS or Unix, ./check_requirements.bat on Windows.

  3. Check the report and adapt.

If you install a new tool, you might need to restart your terminal/prompt before running the script again. (The PATH variable must be refreshed.)
If you have some problems with this script, please feel free to create a new issue here.
Method 2 - Manual check (if above "method 1" doesn’t work)

If you want, you can check following file to know the min and max versions for each tool: https://github.com/green-code-initiative/creedengo-common/blob/main/tools/check_requirements/config.txt

You can use the following commands to see the version of the tools installed on your machine, and check they’re compliant:

docker --version
docker-compose --version
java --version
mvn --version
git --version
jq --version

Get source code

Clone the project you will work with (standard, mobile or/and common) Please see all available repositories here.

Example for Java plugin (with SSH)
git clone git@github.com:green-code-initiative/creedengo-java.git
If you are a new contributor (as opposed to an identified project maintainer), you have to use FORK / Pull Request System like explained here.

Start local environment

You will find all steps to start and configure your local Sonarqube dev Environment here:

  1. Build your local plugin: howto.

  2. Launch local Sonarqube (with installation of previous local plugin built): howto.

  3. Check that local environment is running perfectly:

    • For languages other than Java and Python:

      1. Choose the corresponding "-test-project"-suffixed repository (e.g. https://github.com/green-code-initiative/creedengo-php-test-project).

      2. Launch script tool_send_to_sonar.sh (using the security token created on the second step).

      3. Open your local SonarQube GUI (http://localhost:9000) to verify if the project alone raises Creedengo errors.

    • For Python and Java plugin, please check below. There is no test project anymore, it is inside the plugin’s repository, under src/it/test-projects.

Implement a new rule

Requirements

Please see Initialize local development above.

Choose the rule you want to implement

Once your local environment is running, you can pick a rule waiting to be implemented.

Many ways to do this:

Before implementing a rule, please check if the rule is not already implemented in another language and the id already exists in rules.adoc file or in creedengo-rules-specifications repository. If the rule is already implemented, please use the same id.

Check Definition of Done for new rule implementation

For a new rule implementation, we strongly recommend you to follow this check-list:

  • Check if rule doesn’t exist in our referential rules list yet (rules.adoc file of creedengo-rules-specifications repository)

  • Create PR on the creedengo-rules-specifications repository to add the new rule definition

    • To choose the new rule id:

      • if rule is already existing in rules.adoc file or in creedengo-rules-specifications module, please use the given rule id

      • if rule doesn’t already exist in rules.adoc file or in creedengo-rules-specifications module, please use a random number between 1000 and 1500 (ex : "EC1289") and use it (later, you will be asked to change it)

    • You can use SNAPSHOT version of creedengo-rules-specifications during your local rule implementation to go forward

  • Implement rule in your local specific language repository with a reference to local SNAPSHOT of creedengo-rules-specifications (previously, install it locally with maven command)

    • Write Unit tests (and maximize code coverage)

    • Update CHANGELOG.adoc file (inside Unreleased section)

  • Create PR on the real test project to add a triggering case (check Start local environment))

    • WARNING Java and Python plugin: check above (Specific real test project for Python and Java plugin)

  • Fix potential SonarCloud issues / out-of-date warnings (report is sent after creating PR)

  • In next review step, reviewer will ask you to use a specific id rule if you have chosen a random one

Test your rule implementation

  • First kind of test : Unit tests (please check Definition of Done above)

  • Second kind of test : End-to-End tests in a real local environment (please check Definition of Done above and local procedure )

Each rule needs to have scripts in a specific language (i.e. Python, Rust, JS, PHP and JAVA) in order to test directly inside Sonarqube that the rule has been implemented. To validate that the rule has been implemented, you need to execute a scan on those scripts. You will need sonar scanner: https://docs.sonarqube.org/latest/analysis/scan/sonarscanner/

Specific real test project for Python and Java plugin

These two plugins doesn’t have a specific test project yet in a separated repository. We are deploying in all plugins, a new system to make real tests based on integration tests inside each plugin. The purpose of this system is to be independent of Docker to launch integration tests. Now, we needn’t Docker to launch integration tests. We can use a simple maven command to launch a Sonarqube instance and play the integration tests:

mvn clean verify

If you want to keep your local Sonarqube instance, you can use this maven command (using a maven profile):

mvn clean verify -Pkeep-running

You can find this new real tests system inside src/it directory:

  • subdirectory java contains:

    • system source-code

    • the only one integration test that will be used to launch the integration tests: GCIRulesIT.java

  • subdirectory test-projects contains the real test projects (the old one that was in a separated repository)

Publish your work

Commit your code

Create a new branch following this pattern: <rule_id>-<language>

Example
git checkout -b 47-JS

Commit your code:

git add .
git commit -m "your commit message"

Push your branch:

git push origin <rule_id>-<language>

You may have to login with your account: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token

Open pull request

Once your code is pushed and tested, open a PR between your branch and main: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request

Review others development

Ask to people to review your PR. Once two people, at least, have reviewed, you can validate your PR. If you want to be reviewed, review others…​ It’s a win/win situation

Validation of a PR

Validate your PR or ask someone who have the permissions to validate your PR. Once PR validated, a GitHub workflow is automatically launched. Thus, the new implemented code is also scanned with our internal Sonar to check its quality. Here is the SonarQube: https://sonarcloud.io/organizations/green-code-initiative/projects

Close your rule

Once your PR is validated, your rule integrates creedengo. In the project’s Kanban, move it from the "In Progress" column to the "Done" column. Well done! 🎊