The "Publish PR preview" workflow fails with branch name containing parentheses

[vhemery]

PR https://github.com/bonitasoft/bonita-doc/pull/2309 was opened on a branch named "docs(2022.2)-Update-release-note-for-7.15.2". Parentheses are not supported by the publication script. We also get errors such as

[16:21:45.864] ERROR (asciidoctor): target of xref not found: 2022.2@bonita:software-extensibility:bonita-repository-access.adoc#bonita-artifact-repository
    file: modules/ROOT/pages/installation.adoc:17
    source: https://github.com/bonitasoft/bonita-test-toolkit-doc.git (branch: 1.0)

caused by the fact that the branch is not considered, as shows the warning

[16:21:35.865] WARN (@antora/content-classifier): Start page specified for site not found: 2022.2@bonita::index.adoc

and the log listing versions

[16:21:35.869] INFO (bonita-versions-sorter): Start sorting
...
[16:21:35.870] INFO (bonita-versions-sorter): Processing component bonita
[16:21:35.872] INFO (bonita-versions-sorter): Component bonita versions [{"version":"2022.1","displayVersion":"2022.1"},{"version":"2021.1","displayVersion":"2021.1"}]

Easy workaround : just rename the branch and open a new PR.

[tbouffard]

When using a branch with such a name (including brackets), Antora doesn't consider the branch. This may be a limitation or a bug in Antora. We are not going to investigate but instead validate the branch name to ensure it follows a pattern that works with Antora. Based on discussion with @benjaminParisel, we are going to allow the characters that are commonly used by Bonitasoft developers when naming their branches

• alpha-numeric
• dot .
• slash /
• dash -
• underscore _

To achieve this, we will add a step in the action building the site (PR preview and buid site for xref validation) This can be done with https://github.com/goshencollege/validate-branch-name or by using its implementation directly in js https://github.com/goshencollege/validate-branch-name/blob/v1.0.1/index.js

In addition, I have detected an issue in the "PR preview" action. The command use to build the preview doesn't escape the branch name by adding double quotes as this is done everywhere else. I will also add the double quote.

Run ./build-preview.bash --component bonita --branch docs(2022.2)-Update-release-note-for-7.15.2 --ignore-error true --fetch-sources true --pr "2309" --site-url "https://bonitasoft-bonita-doc-build_preview-pr-2309.surge.sh/" /home/runner/work/_temp/fd2729d7-a393-475e-8b6d-e3c65b527882.sh: line 1: syntax error near unexpected token `('

I will reopen the PR https://github.com/bonitasoft/bonita-doc/pull/2309 to test what is proposed here.