Merge branch 'develop' into 20.0-anex

.github/CONTRIBUTING.md

@@ -1,56 +1,89 @@
 How to contribute to Dolibarr
 =============================
 
-Bug reports and feature requests
---------------------------------
+Submit a Bug report or a Feature request
+---------------------------------------
 
-<a name="not-a-support-forum"></a>*Note*: **GitHub Issues is not a support forum.** If you have questions about Dolibarr / need help using the software, please use [the forums](https://www.dolibarr.org/forum.php). Forums exist in different languages.
+<a name="not-a-support-forum"></a>*Note*: **GitHub Issues is not a support forum.**  
+If you have questions about Dolibarr or need help on using the software, please use [the forums](https://www.dolibarr.org/forum.php). Forums exist in different languages.
 
-Issues are managed on [GitHub](https://github.com/Dolibarr/dolibarr/issues). 
-Default **language here is English**. So please prepare your contributions in English.
+Issues to inform about a bug or a development trouble and requests for a new feature, are managed on [GitHub](https://github.com/Dolibarr/dolibarr/issues).
+Default **language here is English**. So please prepare your contributions in English (we recommend using an online translation service if you don't speak English).
 
-1. Please [use the search engine](https://help.github.com/articles/searching-issues) to check if nobody's already reported your problem.
+1. Please [use the search engine](https://help.github.com/articles/searching-issues) to check if anyone else has already reported your issue.
 2. [Create an issue](https://help.github.com/articles/creating-an-issue). Choose an appropriate title. Prepend appropriately with Bug or Feature Request.
 3. Tell us the version you are using!   (look at  /htdocs/admin/system/dolibarr.php?  and check if you are using the latest version) 
 4. Write a report with as much detail as possible (Use [screenshots](https://help.github.com/articles/issue-attachments) or even screencasts and provide logging and debugging information whenever possible).
 5. Delete unnecessary submissions.
-6. **Check your Message at Preview before sending.**
+6. **Check your Message at Preview before submitting.**
 
 
 
-<a name="code"></a>Submit code
+<a name="code"></a>
+
+Submit code
 ---------------------
 
+This process describes how a Developer can submit code to the project so it can be analyzed and validated by the PR Maintainer (we call this a Pull Request).
+
+Definition:
+- Developer: is the human knowing the development language of the application that wants to change some part of the code by modifying the sources of the project.
+- PR Maintainer: is the human knowing the development language and code who checks that the code submitted for approbation is correct to validate it, in other words, the PR Maintainer is the approbator of commits. 
+- Release Maintainer: is the human that validates that a freeze/beta version is ok to be released officially as a stable version.
+
+
 ### Basic workflow
 
+As the Developer:
+
 1. [Fork](https://help.github.com/articles/fork-a-repo) the [GitHub repository](https://github.com/Dolibarr/dolibarr).
 2. Clone your fork.
 3. Choose a branch(See the [Branches](#branches) section below).
 4. Read our developer documentation on the [Dolibarr Wiki](https://wiki.dolibarr.org/index.php?title=Developer_documentation).
 5. Commit and push your changes.
 6. [Make a pull request](https://help.github.com/articles/creating-a-pull-request).
 
+As the PR Maintainer:
+
+7. The PR Maintainer will check and decide if he approves or not the commits. During this step, the PR Maintainer can modify your own code to make it valid for approbation or ask you to make the change yourself. For this the PR Maintainer may add commits to a PR. Depending on the tools used (can be done from github directly or from an IDE), such commits may be done directly after validating your PR (for example to complete it).
+
+As the Release Maintainer:
+
+8. A tag will be added to take a snapshot of the code with all the changes approved by PR Maintainers, when ready to do a release.
+
+
+Note: Project leader(Master Yoda and BDFL) retains all above roles and can directly commit to the project without a PR. Of course anyone can check commit history and comment!
+
 
 <span id="branches" name="branches"></span>
+
 ### Branches
 
 Unless you're fixing a bug, all pull requests should be made against the *develop* branch.
 
-If you're fixing a bug, it is preferred that you cook your fix and pull request it against an oldest version affected.
+If you're fixing a bug, it is preferred that you make a pull request against the oldest version affected.
+
+We recommend to push it into N - 2 where N is the latest version available, if not possible into version N - 1, and finally into develop.
 
-We recommend to push it into N - 2 for N the latest version available, if not possible into version N - 1, and finally into develop.
-This is just a recommendation, currently, if you push a bug fix on a very old version, it is still merged and propagated into
-higher versions. 
+The rule N - 2 is just a tip if you don't know which version to choose to get the best compromise between ease of correction and number of potential beneficiaries of the correction.
+
+If you push a bug fix on a very old version it is still going to be merged and propagated into newer versions(choose wisely because old versions depend on old deprecated/unsupported versions of PHP and external libraries). 
 
-The rule N - 2 is just a tip if you don't know which version to choose to get the best the best compromise between ease of correction 
-and number of potential beneficiaries of the correction.
 
 
 ### General rules
-Please don't edit the ChangeLog file. This file is generated from all commit messages during release process by the project manager.
 
+- As the Developer, please don't edit the ChangeLog file. This file is generated from all commit messages during the release process by the Project releaser.
+
+- As the Developer: Do not submit changes into files xx_XX/afile.lang. They are language files and are updated/synced automatically from Transifex. If you need to add a new language file, just add it for the en_US language.
+
+- As the Release Maintainer: The Release Maintainer will decide to make a new release as soon as the planning of the release is reached and the code in the branch to release reach the status of "No more known serious bugs". 
+
+
+<a name="commits"></a>
+
+### Commits
 
-### <a name="commits"></a>Commits
 Use clear commit messages with the following structure:
 
 ```plaintext
@@ -106,9 +139,9 @@ FIX|Fix #456 Short description (where #456 is number of bug fix, if it exists. I
 or
 CLOSE|Close #456 Short description (where #456 is number of feature request, if it exists. In upper case to appear into ChangeLog)
 or
-NEW|New|QUAL|Qual|PERF|Perf Short description (In upper case to appear into ChangeLog, use this if you add a feature not tracked, otherwise use CLOSE #456)
+NEW|New|QUAL|Qual|PERF|Perf Short description (In upper case to appear into ChangeLog, use this if you add a feature not tracked, otherwise use CLOSE #xxx)
 or
-Short description (when the commit is not introducing feature nor closing a bug)
+Short description (when the commit is not introducing a feature nor closing a bug)
 
 Long description (Can span across multiple lines).
 </pre>
@@ -125,24 +158,24 @@ a process to follow to optimize the chance to have PRs merged efficiently...
 
 * When submitting a pull request, use same rule as [Commits](#commits) for the message. If your pull request only contains 1 commit, GitHub will be smart enough to fill it for you. Otherwise, please be a bit verbose about what you're providing.
 
-* A screenshot will be always required for any PR of change/addition of a GUI behaviour.
+* A screenshot will be always required for any PR of change/addition of a GUI behavior.
 
 Also, some code changes need a prior approbation:
 
-* if you want to include a new external library (into htdocs/includes directory), please ask before to the core project manager (mention @dolibarr-jedi in your issue) to see if such a library can be accepted.
+* if you want to include a new external library (into htdocs/includes directory), please contact the core project manager first (mention @dolibarr-jedi in your issue) to see if such a library can be accepted.
 
 * if you add new tables or fields, you MUST first submit a standalone PR with the data structure changes you plan to add/modify (and only data structure changes). Start development only once this data structure has been accepted.
 
 Once a PR has been submitted, you may need to wait for its integration. It is common that the project leader let the PR open for a long delay to allow every developer discuss about the PR (A label is added in such a case).
 
 If the label of PR start with "Draft" or "WIP" (Work In Progress), it will not be analyzed for merging until you change the label of the PR (but it can be analyzed for discussion).
 
-If your PR has errors reported by the Continuous Integration Platform, it means your PR is not valid and nothing will be done with it. It will be kept open to allow developers to fix this, or it may be closed several month later. Don't expect anything on your PR if you have such errors, you MUST first fix the Continuous Integration error to have it taken into consideration.
+If your PR has errors reported by the Continuous Integration Platform, it means your PR is not valid and nothing will be done with it. It will be kept open to allow developers to fix this, or it may be closed several months later. Don't expect anything on your PR if you have such errors, you MUST first fix the Continuous Integration error to have it taken into consideration.
 
-If the PR is valid, and is kept open for a long time, a tag will also be added on the PR to describe the status of your PR and why the PR is kept open. By putting your mouse on the tag, you will get a full explanation of the tag/status that explain why your PR has not been integrated yet.
-In most cases, it gives you information of things you have to do to have the PR taken into consideration (for example a change is requested, a conflict is expected to be solved, some questions were asked). If you have a yellow, red flag of purple flag, don't expect to have your PR validated. You must first provide the answer the tag ask you. The majority of open PR are waiting an action of the author of the PR.
+If the PR is valid, and is kept open for a long time, a tag will also be added on the PR to describe the status of your PR and why the PR is kept open. By putting your mouse on the tag, you will get a full explanation of the tag/status that explains why your PR has not been integrated yet.
+In most cases, it gives you information of things you have to do to have the PR taken into consideration (for example a change is requested, a conflict is expected to be solved, some questions were asked). If you have a yellow, red flag of purple flag, don't expect to have your PR validated. You must first provide the answer the tag asks you. The majority of open PRs are waiting an action of the author of the PR.
 
-Statistics on Dolibarr project shows that 95% of submitted PR are reviewed and tagged. Average answer delay is also one of the best among Open source projects (just few days before having the Answer Tag set). This is one of the most important ratio of answered PR in Open Source world for a major project. Don't expect the core team to reach the 100%. 
+Statistics on Dolibarr project shows that 95% of submitted PRs are reviewed and tagged. Average answer delay is also one of the best among Open source projects (just few days before having the Answer Tag set). This is one of the most important ratio of answered PRs in Open Source world for a major project. Don't expect the core team to reach 100%. 
 A so high ratio is very rare on a so popular project and with the increasing popularity of Dolibarr, this ratio will probably decrease in future to a more common level.
 
 
@@ -157,9 +190,9 @@ All other translations are managed online at [Transifex](https://www.transifex.c
 
 Translations done on transifex are available in the next major release.
 
-Note: Sometimes, the source text (English) is modified. In such a case, the translation is reset. Transifex assume that if the original source
+Note: Sometimes, the source text (English) is modified. In such a case, the translation is reset. Transifex assumes that if the original source
 has changed, the translation is surely no more correct so must be done again. But old translation is not lost and you can use the tab "History"
-to retrieve all old translation of a source text, and restore the translation in one click with no need to retranslate it if there is no need to.
+to retrieve all old translations of a source text and restore the translation in one click with no need to retranslate it if there is no need to.
 
 
 ### Resources

.github/workflows/cache-clean-pr.yml

@@ -19,17 +19,17 @@ jobs:
       - name: Cleanup
         run: |
           gh extension install actions/gh-actions-cache
-          REPO=${{ github.repository }}
-          BRANCH=refs/pull/${{ github.event.pull_request.number }}/merge
+          REPO="${{ github.repository }}"
+          BRANCH="refs/pull/${{ github.event.pull_request.number }}/merge"
           echo "Fetching list of cache key"
-          cacheKeysForPR=$(gh actions-cache list -R $REPO -B $BRANCH | cut -f 1 )
+          cacheKeysForPR=$(gh actions-cache list -R "$REPO" -B "$BRANCH" | cut -f 1 )
 
-          ## Setting this to not fail the workflow while deleting cache keys. 
+          ## Setting this to not fail the workflow while deleting cache keys.
           set +e
           echo "Deleting caches..."
           for cacheKey in $cacheKeysForPR
           do
-              gh actions-cache delete $cacheKey -R $REPO -B $BRANCH --confirm
+              gh actions-cache delete "$cacheKey" -R "$REPO" -B "$BRANCH" --confirm
           done
           echo "Done"
         env:

.github/workflows/ci.yml

@@ -10,16 +10,17 @@ jobs:
   phan:
     uses: ./.github/workflows/phan.yml
     secrets: inherit
+    needs: [pre-commit]
     with:
       gh_event: ${{ github.event_name }}
   phpstan:
     uses: ./.github/workflows/phpstan.yml
     secrets: inherit
-    needs: [pre-commit, phan]
+    needs: [pre-commit]
     with:
       gh_event: ${{ github.event_name }}
   windows-ci:
-    needs: [pre-commit, phan]
+    needs: [pre-commit, phpstan, phan]
     secrets: inherit
     uses: ./.github/workflows/windows-ci.yml
     with:
@@ -35,6 +36,6 @@ jobs:
 
 
 # Note (not tested, from https://github.com/orgs/community/discussions/38361)
-# To cancel jobs if one failes, the following action may help
+# To cancel jobs if one fails, the following action may help
 #       - if: "failure()"
 #        uses: "andymckay/[email protected]"

.github/workflows/exakat.yml

@@ -4,10 +4,8 @@ name: "Exakat analysis"
 on:
   # execute once a month, the 1st
   schedule:
-  - cron: "0 20 1 * *"
+    - cron: "0 20 1 * *"
   workflow_dispatch:
-    branches:
-      - develop
 
 permissions:
   contents: read
@@ -19,6 +17,7 @@ jobs:
     - uses: actions/checkout@v4
       with:
         fetch-depth: 1
+        ref: develop
     - name: Exakat
       uses: docker://exakat/exakat-ga
       with:

.github/workflows/phan.yml

@@ -17,8 +17,7 @@ concurrency:
   cancel-in-progress: true
 env:
   gh_event: ${{ inputs.gh_event || github.event_name }}
-  PHAN_CONFIG: >
-    ${{ 'dev/tools/phan/config.php' }}
+  PHAN_CONFIG: dev/tools/phan/config.php
   PHAN_BASELINE: dev/tools/phan/baseline.txt
   PHAN_MIN_PHP: 7.0
   PHAN_QUICK: ${{ github.event.schedule && '' || '--quick' }}
@@ -43,7 +42,8 @@ jobs:
           tools: cs2pr,phan
       - name: Run Phan analysis
         run: |
-          phan $PHAN_QUICK -k $PHAN_CONFIG -B $PHAN_BASELINE --analyze-twice --minimum-target-php-version $PHAN_MIN_PHP --output-mode=checkstyle -o _phan.xml
+          # shellcheck disable=2086
+          phan $PHAN_QUICK -k "$PHAN_CONFIG" -B "$PHAN_BASELINE" --analyze-twice --minimum-target-php-version "$PHAN_MIN_PHP" --output-mode=checkstyle -o _phan.xml
       - name: Add results to PR
         if: ${{ always() }}
         run: |

.github/workflows/phpstan.yml

@@ -44,7 +44,7 @@ jobs:
         uses: shivammathur/setup-php@v2
         with:
           php-version: ${{ matrix.php-version }}
-          tools: phpstan, cs2pr
+          tools: phpstan:1.12, cs2pr
           extensions: calendar, json, imagick, gd, zip, mbstring, intl, opcache, imap,
             mysql, pgsql, sqlite3, ldap, xml, mcrypt
 

.github/workflows/pre-commit.yml

@@ -32,7 +32,7 @@ jobs:
       # This is faster for a big repo.
       - name: Get all changed php files (if PR)
         id: changed-php
-        uses: tj-actions/changed-files@v44
+        uses: tj-actions/changed-files@v45
         if: env.gh_event == 'pull_request'
         with:
           files: |
@@ -67,12 +67,12 @@ jobs:
         run: |
           set -o pipefail
           pre-commit gc
-          pre-commit run --show-diff-on-failure --color=always --all-files | tee ${RAW_LOG}
+          pre-commit run --show-diff-on-failure --color=always --all-files | tee "${RAW_LOG}"
 
       # The next uses git, which is slow for a bit repo.
       # - name: Get all changed php files (if PR)
       #   id: changed-php
-      #   uses: tj-actions/changed-files@v44
+      #   uses: tj-actions/changed-files@v45
       #   if: env.gh_event == 'pull_request'
       #   with:
       #     files: |
@@ -105,7 +105,8 @@ jobs:
           ALL_CHANGED_FILES: ${{ steps.changed-php.outputs.all_changed_files }}
         run: |
           set -o pipefail
-          pre-commit run php-cs --files ${ALL_CHANGED_FILES} | tee -a ${RAW_LOG}
+          # shellcheck disable=2086
+          pre-commit run php-cs --files ${ALL_CHANGED_FILES} | tee -a "${RAW_LOG}"
 
       - name: Run some pre-commit hooks on all files on push to "main" branches
         if: |
@@ -117,8 +118,8 @@ jobs:
         run: |
           set -o pipefail
           ln -sf ~/.cache .cache  # Absolute path in .pre-commit-config.yaml
-          pre-commit run --hook-stage manual -a php-cs-with-cache | tee -a ${RAW_LOG}
-          pre-commit run --hook-stage manual -a sqlfluff-lint | tee -a ${RAW_LOG}
+          pre-commit run --hook-stage manual -a php-cs-with-cache | tee -a "${RAW_LOG}"
+          pre-commit run --hook-stage manual -a sqlfluff-lint | tee -a "${RAW_LOG}"
           ls -l ~/.cache/pre-commit/
 
       - name: Convert Raw Log to Annotations

.github/workflows/windows-ci.yml

@@ -61,7 +61,7 @@ jobs:
           KEY_ROOT: ${{ matrix.os }}-${{ env.ckey }}-${{ matrix.php_version }}
         with:
           # See https://github.com/actions/cache/issues/1275#issuecomment-1925217178
-          enableCrossOsArchive: true 
+          enableCrossOsArchive: true
           path: |
             ./db_init.sql
             ./db_init.sql.md5
@@ -116,6 +116,7 @@ jobs:
         # Note this is bash (MSYS) on Windows
         shell: bash
         run: |
+          # shellcheck disable=SC2129
           ECHO "#[group]Directory contents to verify cache files, ..."
           ls -l
           ECHO "#[endgroup]"
@@ -130,10 +131,12 @@ jobs:
           ls -l
           ECHO "#[endgroup]"
           # Export some tool paths to reuse the from CMD shell.
-          echo "TAIL=$(cygpath -w "$(which tail)")" >> "$GITHUB_ENV"
-          echo "GREP=$(cygpath -w "$(which grep)")" >> "$GITHUB_ENV"
-          echo "TEE=$(cygpath -w "$(which tee)")" >> "$GITHUB_ENV"
-          echo "BASEDIR=$(realpath .)" >> "$GITHUB_ENV"
+          {
+          echo "TAIL=$(cygpath -w "$(which tail)")"
+          echo "GREP=$(cygpath -w "$(which grep)")"
+          echo "TEE=$(cygpath -w "$(which tee)")"
+          echo "BASEDIR=$(realpath .)"
+          } >> "$GITHUB_ENV"
 
       - name: Run PHPUnit tests
         # continue-on-error: true
@@ -186,7 +189,7 @@ jobs:
         if: ${{ ! cancelled() }}
         with:
           # See https://github.com/actions/cache/issues/1275#issuecomment-1925217178
-          enableCrossOsArchive: true 
+          enableCrossOsArchive: true
           key: ${{ steps.cache.outputs.cache-primary-key }}
           path: |
             ./db_init.sql

.gitignore

@@ -41,6 +41,7 @@ htdocs/includes/php-parallel-lint/
 htdocs/includes/sebastian/
 htdocs/includes/squizlabs/
 htdocs/includes/webmozart/
+htdocs/install/install.forced.php
 htdocs/.well-known/apple-developer-merchantid-domain-association
 /factory/
 /output/