Docs sync

.github/workflows/lint_build.yaml

@@ -7,6 +7,8 @@ on:
     branches:
       - main
       - 'release-*'
+    paths-ignore:
+      - 'docs/**'
   workflow_dispatch:
 jobs:
   lint_and_build:

.github/workflows/sync_docs_branch.yaml

@@ -0,0 +1,42 @@
+name: Sync docs branch
+# The GitBook space syncs with the gitbook branch, because main only accepts pull requests.
+# On every merge to main, and once a day, fast-forward gitbook to main so docs edited in the
+# repository reach GitBook. When gitbook is ahead because edits were merged in the GitBook
+# editor, open the pull request that carries them to main. The built-in token is enough:
+# a pull request it creates triggers no Actions workflows, and the test workflows skip
+# docs-only pull requests anyway, while the GitBook preview comes from the GitBook app.
+on:
+  push:
+    branches:
+      - main
+  schedule:
+    - cron: '0 9 * * *'
+  workflow_dispatch:
+permissions:
+  contents: write
+  pull-requests: write
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Fast-forward gitbook to main
+        id: fast_forward
+        continue-on-error: true
+        run: git push origin main:gitbook
+      - name: Open the docs pull request when gitbook is ahead
+        if: steps.fast_forward.outcome == 'failure'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+        run: |
+          existing=$(gh pr list --head gitbook --base main --state open --json number --jq '.[0].number')
+          if [ -n "$existing" ]; then
+            echo "docs pull request #$existing is already open"
+            exit 0
+          fi
+          gh pr create --base main --head gitbook \
+            --title "docs: changes from GitBook" \
+            --body "Edits merged in the GitBook editor, synced from the gitbook branch."

.github/workflows/unit_tests.yaml

@@ -7,6 +7,8 @@ on:
     branches:
       - main
       - 'release-*'
+    paths-ignore:
+      - 'docs/**'
   workflow_dispatch:
 jobs:
   test:

docs/help-and-support/raise-a-bug.md

@@ -1,3 +1,27 @@
 # Raise a bug
 
-link to github when available
+Bugs and feature requests for IDEA are tracked on GitHub, and anyone can open one.
+
+* **Report a bug:** [open a new issue](https://github.com/cfs-energy/idea/issues/new/choose) and choose **Bug report**.
+* **Request a feature:** the same page, choose **Feature request**.
+* **Ask a question:** [GitHub Discussions](https://github.com/cfs-energy/idea/discussions).
+
+Search the [open issues](https://github.com/cfs-energy/idea/issues) first; the problem may already be known.
+
+## What to include
+
+* **The IDEA version:** the contents of `IDEA_VERSION.txt` in the release you deployed, or the `idea-administrator` image tag you ran (for example `26.09.0`).
+* **Where it happened:** the web portal, the cluster manager, the scheduler, virtual desktops, the installer or an upgrade; the base OS of the host or desktop involved; the AWS region and partition.
+* **Steps to reproduce**, what you expected, and what happened instead.
+* **The exact error text:** the message on screen for the portal, the full command output for `idea-admin.sh`.
+* **Logs from the module host** for the minutes around the failure: `/opt/idea/app/logs/application.log`. For an installer or upgrade failure, add the CloudFormation stack status and the failed resource's status reason.
+* **Screenshots** for anything visual.
+* Whether you changed IDEA from the published release, and if so what.
+
+## What not to include
+
+Issues are public. Remove credentials, tokens, account ids, private hostnames and IP addresses before pasting logs or screenshots.
+
+## Security issues
+
+Do not put exploit details in a public issue. Open an issue that says only that you have a security finding and how a maintainer can reach you, and a maintainer will follow up privately.