User guide

May 19, 2026 · View on GitHub

User guide

Here is th global User Guide for creedengo plugins : USER-GUIDE.md

Basic Explanations

In order to develop a Sonarqube Plugin in Open source for creedengo, the following sections 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/ But ... we are going to help you more specifically for creedengo project in the following sections by examples.

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.

Some Creedengo plugins (Javascript, Csharp) work differently because they don't parse the code to transform it into an AST themselves, they use the internal linter engine (ex : ESLint for Javascript) which does the parsing by itself (More information here). The good part is that it means for Javascript for example, that all creedengo JavaScript rules are made available both to Sonar and to ESLint through an 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

This is the purpose of all this document.

Github Green-Code-Initiative

Some rules references

115 web rules details

https://github.com/cnumr/best-practices

40+ android/iOS rules details

https://github.com/cnumr/best-practices-mobile

Initialize local development

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

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

Requirements

Having a Github account with a valid email.

Method 1 - Automatic check (default method)

In this current repository, go to tools/check_requirements directory. Next, execute script verification and check the result :

For Mac or Unix OS : ./check_requirements.sh For Windows OS : ./check_requirements.bat

PS : if you have some problems with this script, please feel free to create a new issue here https://github.com/green-code-initiative/creedengo-common/issues

Method 2 - Manual check (if above "method 1" doesn't work)

If you want, you can check following file to know what are min and max versions for each tool : https://github.com/green-code-initiative/creedengo-common/blob/main/tools/check_requirements/config.txt If no version for a specific too implies that there isn't neither min version nor max version. Thus, the script will only check if the tool is installed and working.

Then launch check commands as follows, check the tool is working and check versions displayed) :

docker --version
docker-compose --version
javap -version
mvn --version
git --version
jq --version

Get source code

Clone the wanted project (standard, mobile or/and common) : please see all availables repositories here https://github.com/orgs/green-code-initiative/repositories?type=all

Example for Java plugin (with SSH) :

git clone git@github.com:green-code-initiative/creedengo-java.git

WARNING : if you are a new contributor (and not identified project maintainer), you have to use FORK system and PULL REQUESTS like explained here https://github.com/green-code-initiative/creedengo-common/blob/main/doc/HOWTO.md#howto-develop-in-open-source-mode

Start local environment

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

Implement a new rule

Requirements

please see section above Initialize local development

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 :

  • FIRST WAY : choose a rule in following tables that is ready to implement (🚀) or has to be analyzed (❓)
  • SECOND WAY : pick a plugin in the table bottom and check if a rule is waiting to be implemented.
Plugin LanguagePlugin Rules Ideas
Java💡 rule-idea
JavaScript🗃️ rule or 💡 rule-idea
HTML🗃️ rule or 💡 rule-idea
  • THIRD WAY : pick a idea rule (not yet analyzed) and check if a rule is waiting to be implemented.
RepositoryPlugin Rules Ideas
creedengo-common💡 rule-idea
creedengo-challenge💡 rule-idea
  • FOURTH WAY : check rule ideas in Kanban project board here and select implementable (or hardly implementable) ticket, and create an issue in the right language repositoyr
  • FIFTH WAY : Go and give a hand to the spotters team who will give you some rules to implement

IMPORTANT : before implementing a rule, please check if the rule is not already implemented in another language and the id already exists in RULES.md file in creedengo-rules-specifications repository. If the rule is already implemented, please use the same id.

FIRST, Declare the new rule / language in creedengo-rules-specifications repository

Choose the ID rule

EXISTING RULE, but new language

Use the existing rule id in RULES.md.

NEW RULE (not already existing)

Use a random number between 2000 and 3000 (ex : "GCI2289") and use it for your code. Later, during PR reviewing process, you will be asked to change it.

Technical declaration

Content of creedengo-rules-specifications

In creedengo-rules-specifications repository, here is the content :

  • each rule is declared inside directory src/main/rules with following requirements :
    • one directory for each rule (ex : GCI34)
      • JSON root file (ex : GCI34.json) : contains SonarQube metadata
      • one sub-directory per language (ex : python)
        • ASCIIDOC file (ex : GCI34.asciidoc) : description of rule to be displayed into Sonar
          • IMPORTANT : you have to describe the rule behaviour with examples (compliant and not compliant) and give references proving the benefit of the rule

UPGRADE : Existing rule, but new language

In creedengo-rules-specifications repository, declare the new language :

  • inside the rule directory present in src/main/rules (ex : GCI34) :
    • add a new sub-directory for new language (ex : python)
    • in the new language sub-directory, add the ASCIIDOC file (ex : GCI34.asciidoc based on the other ASCIIDOC file)
  • upgrade CHANGELOG.md

UPGRADE : new rule (not already existing)

In creedengo-rules-specifications repository, declare the new rule :

  • add the new rule in directory src/main/rules with following requirements :
    • one directory for each rule : create the directory if new rule (ex : GCI34)
    • inside the rule directory (ex : GCI34)
      • add the JSON root file (containing SonarQube metadata) (ex : GCI34.json)
      • one sub-directory per language
        • create the directory for the new langugage (ex : python)
        • add the ASCIIDOC file (description of rule to be displayed into Sonar) (ex : GCI34.asciidoc)
  • upgrade CHANGELOG.md

Install locally

In order to be used in your plugin, you have to install locally your creedengo-rules-specifications component, because it is used as a dependency in the plugin : inside creedengo-rules-specifications repository directory, launch the following command : mvn install. This will install locally the creedengo-rules-specifications component in your local maven repository with a SNAPSHOT version. You can see this version in the result console.

SECOND, usage inside creedengo-<LANGUAGE> repository

Local creedengo-rules-specifications dependency

Once your creedengo-rules-specifications component is installed locally (please see previous section), you can use it inside your plugin repository :

  • inside pom.xml, upgrade the version of the dependency creedengo-rules-specifications to use your SNAPSHOT version installed locally previsouly
  • launch a build of the project

Check there is no error during build step. Your plugin is ready to use the new rule for your plugin.

Develop you rule

You can use an existing example (implementation class) and add your own one. You can take an example wth already implemented rules.

Inside your plugin project, you can now :

  • add a new rule implementation class (and use the @Rule annotation ti use the new rule)
  • declare this implementation class in the system
  • add a new unit test class with at minimum a compliant and an non compliant use case
  • add a new integration test with the same minimum (GCIRuleIT class) for Java, Php an Python plugins : please see section under

Test your rule implementation

  • First kind of test : Unit tests (please check Definition of Done bottom)
  • Second kind of test :
    • For neither Java, nor Php, nor Python plugins : End-to-End tests in a real local environment (please check Definition of Done above and local procedure )
    • For Java, Php, Python plugins : Integration Tests described in the next section

For End-to-End tests :

  • 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 Java, Python and PHP plugins

These three 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 based on a real local Sonarqube instance. 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 (to check some things for example), 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 :

  • sub-directory java contains :
    • system source-code
    • the only one integration test that will be used to launch the integration tests : GCIRulesIT.java
  • sub-directory test-projects contains the real test projects (the old one that was in a separated repository)
    • if you really want to launch End-to-End tests, you can do it because you can find scripts to do it inside.

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.md 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.md file in creedengo-rules-specifications module, please use the given rule id
      • if rule doesn't already exist in RULES.md file in creedengo-rules-specifications module, please use a random number between 2000 and 3000 (ex : "GCI2389") 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)
    • Write Integration tests (based on Unit Tests and same resource test files) for Java, Python and Php plugins
    • Write End-to-End test (based on Unit Tests and same resource test files) for plugins different from Java, Python and Php
    • Update CHANGELOG.md file (inside Unreleased section)
  • for plugins different from Java, Python and Php, create PR on the real test project to add a triggering case (check local procedure)
  • OPTIONAL - 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

for existing rule implementation (bug or improvment)

  • Improve rule in your local specific language repository
    • Write / adapt Unit tests (and maximize code coverage)
    • Write / adapt Integration tests (based on Unit Tests and same resource test files) for Java, Python and Php plugins
    • Write End-to-End test (based on Unit Tests and same resource test files) for plugins different from Java, Python and Php
    • Update CHANGELOG.md file (inside Unreleased section)
  • for plugins different from Java, Python and Php, create PR on the real test project to add a triggering case (check local procedure)
  • OPTIONAL - Fix potential SonarCloud issues / out-of-date warnings (report is sent after creating PR)

Publish your work

Commit your code

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

git checkout -b 47-JS

Commit your code :

git add .
git commit -m "your comments"

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 in your pesonal repository and "main" in official repository : 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 to 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 the implemented code 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 https://github.com/cnumr/creedengo/projects/1, move it from the "In Progress" column to the "Done" column. Well done.