Global Requirements

You should see two lines (one for sonarqube and one for postgres). Please note the assigned port to your local SonarQube (9000 port used for SonarQube server inside Docker container / the other port is the one you can use to access from your web browser)

Result example :

If there is only postgres, check the logs:

./tool_docker-logs.sh

Wait until "Sonarqube is operational" log appears. And next, your SonarQube instance is ready to use.

You can now type in "CTRL-C" to exit logs.

Errors

If you have this error on run: web_1 | [1]: max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144] you can allocate more virtual memory:

sudo sysctl -w vm.max_map_count=262144

For Windows:

wsl -d docker-desktop
sysctl -w vm.max_map_count=262144

Configuration SonarQube

Purposes : Configure SonarQube to have all creedengo plugins rules enabled by default.

Change password

go to your SonarQube homepage http://localhost:XXXXX/ (XXXX : external docker port used. You can get it when you list available Docker containers)
use default credentials : admin/ admin
the first time after first connection, you are suggested to change admin password

Check plugins installation

go to "Adminitration" tab
go to "Marketplace" sub-tab
go bottom, and click on "Installed" sub-tab
check here, if you have creedengo plugins displayed with a SNAPSHOT version

Generate access token

When you are connected,

generate a new token on My Account -> Security -> Generate Tokens with "User token" type
copy it for following steps

Security tab

Instead of login+password authentication, this token can now be used as value for sonar.login variable when needed (examples : call sonar scanner to send metrics to SonarQube, on use internal tools, ...)

Initialize default profiles for `creedengo` plugins

use tool install_profile.sh in creedengo-common repository (inside directory tools/rules_config)
- if you want, you can check default configuration of this tool in _config.sh file
launch followed command : ./install_profile.sh <MY_SONAR_PORT> <MY_SONAR_TOKEN>

After this step, all code source for your language will be analyzed with your new Profile (and its activated plugins rules).

HOWTO reinstall SonarQube (if needed)

# first clean all containers and resources used
./tool_docker-clean.sh

# then, build plugins (if not already done)
./tool_build.sh

# then, install from scratch de SonarQube containers and resources
./tool_docker-init.sh

HOWTO start or stop service (already installed)

Once you did the installation a first time (and then you did custom configuration like quality gates, quality profiles, ...), if you only want to start (or stop properly) existing services :


# start WITH previously created token (to do : change the token inside script)
./tool_start_withtoken.sh

# start without previously created token
./tool_start.sh

# stop the service
./tool_stop.sh

HOWTO install new plugin version

Install dependencies from the root directory:

./tool_build.sh

Result : JAR files (one per plugin) will be copied in lib repository after build.

Restart SonarQube

# stop the service
./tool_stop.sh

# start the service
./tool_start.sh

Contribution / concrete development

HOWTO develop in open-source mode

There are two ways to develop in an open-source project :

you are an official maintainer
you are a contributor

Maintainer, write permission

If you are an official maintainer identified in the project, you are in a special team with write permissions. Thus you can :

create branches and commit directly inside
push code directly on project (by the PR way)
review and accept Pull Requests

Contributor, NO write permissions

If you are a new (or regular) contributor, and you don't have specific write permissions but only read permissions. If you want to contribute to the project, you must use the FORK / Pull Request (PR) system. But don't worry, if you are a regular contributor, project core-team members evaluates, on a regular basis, some contributors to be maintainers !!!

To contribute with FORK / PR system, you have to :

create a fork of the original project (by clicking on Create a new fork button, inside top-right fork menu)
- check that the new project fork is really present in your personal github projects
clone your personal forked project
- you can see on github, you have
  - two new buttons to interact with original project : "Contribute" and "Sync fork"
  - a status information about synchronization between your forked project and original project (on the left of previous new buttons)
- if your fork is recently created, you can see in the status information that your forked project is synchronized
- if not "synchronized", you can click on "Sync fork" to update your forked project from the original project
create a new local branch to begin development
once development done, you can commit and push your work to your github forked project
once all is ok, you can create a new Pull Request to original Project by clicking on the new appeared message with "Compare & pull request" button
- a new PR form is displayed and you can fill it
TIPS : when you have already created the PR to the original project, and you improve the branch of your forked project (with new commits), the PR in original project is automatically updated. Please mark this PR as "Draft", meaning you are still working on it (top-right link "convert to draft" in PR inside original project)

HOWTO debug a rule (with logs)

Add logs like in OptimizeReadFileExceptions class file
Build plugin JARs with tool_build.sh
Launch local Sonar with tool_docker_init.sh
Launch a sonar scanner on an exemple project with mvn verify command (only the first time), followed by :
- if token created : mvn org.sonarsource.scanner.maven:sonar-maven-plugin:3.9.1.2184:sonar -Dsonar.login=MY_TOKEN -X
- if login and password : mvn org.sonarsource.scanner.maven:sonar-maven-plugin:3.9.1.2184:sonar -Dsonar.login=MY_LOGIN -Dsonar.password=MY_PASSWORD -X
logs will appear in console (debug logs will appear if -X option is given like above)

HOWTO Deprecate an existing rule

If you want to deprecate an existing rule, you have to follow 2 steps as described below.

STEP 1 : deprecate rule

This step is done on next release of plugin (example : version N).

Upgrade the rule implementation to add deprecation information : in plugin repository containing the rule implementation, add a new @DeprecatedRule annotation on the rule class
Upgrade rules documentation
1. in plugin repository containing the rule implementation, in RULES.md file, move rule line from standard rules array to deprecated rules array
2. in creedengo-rules-specification repository, add deprecation to current rule

Thus in next release of plugin, the rule will be still present but displayed as deprecated in SonarQube UI.

STEP 2 : remove rule

This step is done on release N+2.

Clean implementation code of the rule :
1. in plugin repository containing the rule implementation
  1. delete rule class, clean all references to the rule
  2. delete unit test classes
2. in plugin real test project repository, clean rule test classes
Upgrade rules documentation : in plugin repository containing the rule implementation, in RULES.md file, mark the rule as deleted

HOWTO manage license inside code

documentation of maven plugin "license" : https://oss.carbou.me/license-maven-plugin/#goals

check license in code

mvn license:check

update license in code where license isn't exist

mvn license:format

RELEASING

HOWTO create a release (core-contributor rights needed)

Create a release on DYNAMIC versionning system module

For now, this is ONLY the use case for following respositories :

creedengo-rules-specifications
creedengo-integration-test
creedengo-python

Why dynamic ?

because the versionning is dynamic in this repository.
no need to execute the 2 shell scripts (and commits / pushes) in "static" way to manage the versionning.

upgrade CHANGELOG.md : add release notes for next release
1. Replace Unreleased title with the new version like Release X.Y.Z and the date
  1. ... where X.Y.Z is the new release
  2. ... follow others examples
  3. ... clean content of current release changelog (delete empty sub-sections)
  4. respect Keep a Changelog format
2. add above an empty Unreleased section with sub-sections (Added, Changed and Deleted)
3. add a new section in the list at the bottom of file with new version
4. commit these modifications
upgrade README.md : upgrade if needed and if version compatibility matrix is described
create locally a tag with the previous used version
1. execute git tag <X.Y.Z>
push new tag created previously :
1. locally, go to and update main branch
2. execute git push --tags to push new previously created tag

Next, 2 ways to create JAR files :

for internal components (creedengo-rules-specifications and creedengo-integration-test) :
- no need to create a github release with JAR file, only tag is needed
- after creating a tag (previous step), launch "publish to maven central" github action to deploy a JAR file on maven central
for sonarqube creedengo plugins, we need to create a github release with JAR file, and then create a PR on SonarSource/sonar-update-center-properties to publish the new version on SonarQube Marketplace
- after creating a tag (previous step), launch "tag release" github action to create a github release with JAR file
- then, create a PR on SonarSource/sonar-update-center-properties to publish the new version on SonarQube Marketplace (see above process to publish a new version of a plugin in SonarQube Marketplace)

Create a release on STATIC versionning system module

This is the use case for all plugin repositories except previous listed components on previous dynamic section.

IF new release wanted is a major or minor version (X or Y in X.Y.Z)
1. THEN modify the old version to the new version in all XML/YML files
2. ELSE no modification needed : the new corrective version (Z in X.Y.Z) will be automatic
upgrade CHANGELOG.md : add release notes for next release
1. Replace Unreleased title with the new version like Release X.Y.Z and the date
  1. ... where X.Y.Z is the new release
  2. ... follow others examples
  3. ... clean content of current release changelog (delete empty sub-sections)
  4. respect Keep a Changelog format
2. add above an empty Unreleased section with sub-sections (Added, Changed and Deleted)
3. add a new section in the list at the bottom of file with new version
4. commit these modifications
upgrade README.md : upgrade if needed and if version compatibility matrix is described
prepare locally next release and next snapshot :
1. execute tool_release_1_prepare.sh script to prepare locally the next release and next SNAPSHOT (creation of 2 new commits and a tag)
2. DON'T PUSH, just check locally these 2 commits and tag
create and push new local branch :
1. execute tool_release_2_branch.sh to create and push a new branch with that release and SNAPSHOT
2. check on github that this new branch is created and pushed
create new github PR :
1. on github, create a new PR based on this new branch to main branch
2. check Action launch and result for this new PR
merge PR
1. merge PR on main branch with Create a merge commit option
2. check Action launch and result on main branch
push new tag created previously :
1. locally, go to and update main branch
2. execute git push --tags to push new previously created tag
3. check Action launch and result on new tag

HOWTO publish new release on SonarQube Marketplace

New release from scratch

Create a fork of SonarSource/sonar-update-center-properties and clone it locally
Create a new branch
Change corresponding plugin metadata file (for creedengo-java: creedengojava.properties, for creedengo-php: creedengophp.properties, for creedengo-python: creedengopython.properties):
- Append new version to publicVersions value (comma separated value)
- Add following properties (where X.X.X is new release to publish):
  - X.X.X.description: a summary of main changes for user for this version
  - X.X.X.sqVersions: supported range version of SonarQube
  - X.X.X.date: Release date of plugin (on GitHub Release page)
  - X.X.X.downloadUrl: link to doanwload this specific release
  - X.X.X.changelogUrl: link to detailed change log of this release
Commit and push modifications on your fork
Create a Pull-Request for those modifications on SonarSource/sonar-update-center-properties to annonce new release of the corresponding plugin, with:
- a summary of main changes for user
- the download link
- the link to detailed release note
- the link to SonarCloud corresponding project

Additional information:

Examples :

New release of existing plugin

... quite like "New release from scratch" section above but ...

process : SonarSource documentation - new release
documentation : README.md
example : PR example

HOWTO publish a new version of a plugin in SonarQube Marketplace

Requirements

You need a new release version of the plugin available on GitHub (with a tag).

Give a new Pull Request to SonarSource

Next, we need to create a new Pull Request on SonarSource/sonar-update-center-properties like this example : PR example.

Some rules to respect for a new PR :

update "sqs" (SonarQube Developer Edition) and "sqcb" (SonarQube Community Build) fields
only the last version must use "LATEST" value for sqs and sqcb fields
use download link to get versions value
- sqs (SonarQube Developer Edition)
- sqcb (SonarQube Community Build)
- sqversions : deprecated field

Automatic publish on SonarQube Marketplace

Once this Pull Request is merged, the new version of the plugin will be automatically published on SonarQube Marketplace.

HOWTO publish a new version of creedengo-rules-specifications and and creedengo-integration-test on Maven Central

Requirements

You need write rights to use Maven Central publish process (mainteners or core-team members).

Create a new release of creedengo-rules-specifications and creedengo-integration-test repository : please see above HOWTO create a release.

Why create a new release before ? Because publish process of creedengo-rules-specifications or creedengo-integration-test on Maven Central needs a tag on creedengo-rules-specifications or creedengo-integration-test repository.

Maven Central publish process

go to "Action" tab of creedengo reposiroty
click on "Publish to Maven Central" workflow
click on "Run workflow" list button
choose a tag version (and not a branch because SNAPSHOT version won't be published on Maven Central)
click on "Run workflow" button
check launched workflow on Actions tab and wait for success
go Maven central web site (https://central.sonatype.com), login and click on "publish" tab
wait for the new artifact is uploaded by previous github action process
click on "publish" button
20 minutes later (because of Maven central internal process), check on maven central if new version is published
- check here : https://central.sonatype.com/artifact/org.green-code-initiative/creedengo-rules-specifications/versions

CONFIGURATION

HOWTO configure publish system on Maven Central

requirements : core-contributor rights needed exaplanation :

Update GPG Maven Central keys

What is GPG Maven Central keys ?

GPG system is used to sign JAR files before publishing them to Maven Central. We have to generate public and private keys, and store them in Github Secrets with MAVEN_GPG_PRIVATE_KEY and MAVEN_GPG_PASSPHRASE variables.

These GPG keys are stored in Github Secrets available Settings tab of the repository, in Secrets and variables sub-tab, in Actions sub-section.

How to install and use GPG (command line tool)

Values are generated on local machine with "gpg" command line tool.

on MAC OS (for the moment) :

brew install gpg to install tool
gpg --version to check version of GPG tool
gpg --full-generate-key to generate private and public keys : WARNING, you need to remember passphrase used to generate keys
- Key type : RSA and RSA
- Key size : 4096 (recommended for Maven Central)
- Validity : 0 (no expiration)
- Confirm with "y"
- Name : your name
- E-mail : associated email for Maven Central account
- Comment : keep empty or add a comment
- Confirm with O (for "Okay")
- Give strong passphrase
gpg --list-secret-keys --keyid-format LONG to list keys (and display expiration date) with ID
- key ID is the string after "rsa4096/" (for example : ABCD1234EFGH5678)
gpg --export-secret-keys --armor VOTRE_ID_DE_CLE | pbcopy
- export the private key and copy it to clipboard with armored format

For information, version of GPG command line tool :

$$ gpg --version

gpg (GnuPG) 2.4.3
libgcrypt 1.10.2
Copyright (C) 2023 g10 Code GmbH
License GNU GPL-3.0-or-later <https://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Home: <MY_HOME>/.gnupg
Algorithmes pris en charge :
Clef publique : RSA, ELG, DSA, ECDH, ECDSA, EDDSA
Chiffrement : IDEA, 3DES, CAST5, BLOWFISH, AES, AES192, AES256,
              TWOFISH, CAMELLIA128, CAMELLIA192, CAMELLIA256
Hachage : SHA1, RIPEMD160, SHA256, SHA384, SHA512, SHA224
Compression : Non compressé, ZIP, ZLIB, BZIP2

How to generate new values

Generate new keys with gpg --full-generate-key command : we need to give a passphrase (you can give old one)
Export public key with gpg --export --armor KEY_ID > public-key.asc command
Manual publish of public key on a keyserver website "https://keyserver.ubuntu.com" : copy the content of public-key.asc file and paste it on "Submit a key" page of keyserver website
Check and get public key on website with search on your name

Update Github Secrets

Open exported local file and copy content (only content between -----BEGIN PGP PRIVATE KEY BLOCK----- and -----END PGP PRIVATE KEY BLOCK----- included)
Paste this content in MAVEN_GPG_PRIVATE_KEY variable in Github Secrets on the current repository (Secrets and variables / Actions / Repository secrets)
Paste the passphrase used in previous step, in MAVEN_GPG_PASSPHRASE variable in Github Secrets on the current repository (Secrets and variables / Actions / Repository secrets)
Check below OSSHR token process and then Check publish process with a new release version (see above HOWTO configure publish process on Maven Central)

CONTACT

HOWTO contact the team

Several ways existing :

go to our website https://green-code-initiative.org/ and choose one of different ways :
- on of our 3 social media (top-right menu)
- go to "entreprise" page and you can fill a contact form : https://green-code-initiative.org/#/entreprise
technically : got to our github and create an issue or a discussion
- https://github.com/green-code-initiative