merged and correct/update twincat-ads

.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

.github/workflows/backport.yml

@@ -0,0 +1,33 @@
+name: Backport
+on:
+  pull_request_target:
+    types: [closed, labeled]
+
+# WARNING:
+# When extending this action, be aware that $GITHUB_TOKEN allows write access to
+# the GitHub repository. This means that it should not evaluate user input in a
+# way that allows code injection.
+
+permissions:
+  contents: read
+
+jobs:
+  backport:
+    permissions:
+      contents: write # for korthout/backport-action to create branch
+      pull-requests: write # for korthout/backport-action to create PR to backport
+    name: Backport Pull Request
+    if: github.repository_owner == 'epics-extensions' && github.event.pull_request.merged == true && (github.event_name != 'labeled' || startsWith('backport', github.event.label.name))
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+      - name: Create backport PRs
+        uses: korthout/backport-action@bd410d37cdcae80be6d969823ff5a225fe5c833f # v3.0.2
+        with:
+          # Config README: https://github.com/korthout/backport-action#backport-action
+          branch_name: backport/${pull_number}-to-${target_branch}
+          copy_labels_pattern: 'severity:\ssecurity'
+          pull_description: |-
+            Bot-based backport to `${target_branch}`, triggered by a label in #${pull_number}.

.github/workflows/book-gh-pages.yml

@@ -23,18 +23,18 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - uses: cachix/install-nix-action@v20
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+      - uses: cachix/install-nix-action@ba0dd844c9180cbf77aa72a116d6fbc515d0e87b # v27
       - name: "Build documentation book"
         run: |
           nix build '.#book' --print-build-logs
           cp -Lr --no-preserve=mode,ownership ./result/ ./book
       - name: Setup Pages
-        uses: actions/configure-pages@v3
+        uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v1
+        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3.0.1
         with:
           path: './book'
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v2
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5

.github/workflows/editorconfig.yml

@@ -10,7 +10,7 @@ jobs:
   editorconfig:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
-    - uses: cachix/install-nix-action@v20
+    - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+    - uses: cachix/install-nix-action@ba0dd844c9180cbf77aa72a116d6fbc515d0e87b # v27
     - name: "Check EditorConfig"
       run: nix run 'nixpkgs#eclint' --inputs-from .

.github/workflows/formatting.yml

@@ -10,7 +10,7 @@ jobs:
   alejandra:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
-    - uses: cachix/install-nix-action@v20
+    - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+    - uses: cachix/install-nix-action@ba0dd844c9180cbf77aa72a116d6fbc515d0e87b # v27
     - name: "Check Formatting"
       run: nix fmt -- --check .

.gitignore

@@ -9,3 +9,9 @@ outputs
 # Some files generated by CI, to ensure the working tree is clean on CI
 /manpage
 /public
+
+# Created by running IOCs
+.iocsh_history
+
+# Created by running NixOS tests in interactive mode
+.nixos-test-history

.gitlab-ci.yml

@@ -1,4 +1,9 @@
+workflow:
+  auto_cancel:
+    on_new_commit: interruptible
+
 default:
+  interruptible: true
   tags:
     - nix
 

README.md

@@ -32,7 +32,7 @@ For more information, see the [NixOS modules introduction].
 
 See [over there] in the documentation book.
 
-  [over there]: https://epics-extensions.github.io/EPNix/ioc/tutorials/getting-started.html
+  [over there]: https://epics-extensions.github.io/EPNix/
 
 ## Packaging policy
 
@@ -61,10 +61,6 @@ epnix = {
   # ---
   support.modules = with pkgs.epnix.support; [ StreamDevice ];
 
-  # Add your applications:
-  # ---
-  applications.apps = [ "inputs.myExampleApp" ];
-
   # You can specify environment variables for your development shell like this:
   # ---
   devShell.environment.variables."EPICS_CA_ADDR_LIST" = "localhost";

doc/_quarto.yml

@@ -27,7 +27,8 @@ website:
         - section: User Tutorials
           file: ./ioc/tutorials.md
           contents:
-            - ./ioc/tutorials/getting-started.md
+            - ./ioc/tutorials/pre-requisites.md
+            - ./ioc/tutorials/streamdevice.md
             - ./ioc/tutorials/porting.md
             - ./ioc/tutorials/day-to-day-dev.md
             - ./ioc/tutorials/integration-tests.md

doc/_vale/Vocab/EPNix/accept.txt → doc/_vale/config/vocabularies/EPNix/accept.txt

@@ -14,6 +14,7 @@ NixOS
 NixOps
 procServ
 SELinux
+StreamDevice
 systemd
 RedHat
 [Uu]ntracked

doc/index.md

@@ -41,11 +41,25 @@ However, since EPNix is a git repository, you will be able, through Nix, to use
 ```{=html}
 <!-- TODO: link to an explanation, from the IOC side, and from the NixOS side -->
 ```
+
 ## The epics-base package
 
 The epics-base package has no significant modification compared to the upstream version at [Launchpad].
 One goal of EPNix is to keep those modifications to a minimum, and upstream what's possible.
 
+# Release branches
+
+EPNix has a `master` branch,
+which is considered unstable,
+meaning breaking changes might happen without notice.
+
+EPNix also has release branches,
+such as `nixos-23.11`,
+tied to the nixpkgs release branches,
+where breaking changes are forbidden.
+
+Backporting changes to older release branches is done on a "best-effort" basis.
+
 ------------------------------------------------------------------------
 
 This documentation follows the [Diátaxis] documentation framework.

doc/ioc/faq.md

@@ -22,7 +22,7 @@ Use `<consumerApp>_DEPEND_DIRS += <producerApp>`{.makefile} in your top-level `M
 Meaning, not versioning an App separate from the top.
 This might be justified if you don't intend to share an App in any other top.
 
-1.  First, create a top and an App, as in the [Getting Started] guide.
+1.  First, create a top and an App, as in the [StreamDevice tutorial].
 
 2.  Make sure to add an exception for the `exampleApp` folder at the end of the top's `.gitignore` file:
 
@@ -46,4 +46,4 @@ git add -N .
 
 4.  Finally, in your `flake.nix`, you can remove any input and value in `epnix.applications.apps` that refers to this directory.
 
-  [Getting Started]: ./tutorials/getting-started.md
+  [StreamDevice tutorial]: ./tutorials/streamdevice.md

doc/ioc/guides/flake-registry.md

@@ -2,19 +2,17 @@
 title: Setting up the flake registry
 ---
 
-Since the usage of EPNix doesn't encourage installing epics-base globally, some commonly used command-line programs won't be available in your usual environment.
+While developing with EPNix,
+it's possible you will end up typing `'github:epics-extensions/epnix'` quite often.
 
-It's possible to go into a top, and type `nix develop`{.bash} just to have the `caget`{.bash} command available, but it's quite tedious.
+It happens when you need to create a "top" template,
+or when you just want to have `epics-base` in your shell,
+and so on.
 
-An alternative would be to run:
+This is tedious.
 
-``` bash
-nix develop 'github:epics-extensions/epnix'
-```
-
-This will give you the development shell of EPNix itself, with the added benefit of having the latest version of EPICS base.
-
-The command is quite hard to remember, but with the "registry" feature of Nix, you can shorten it by running:
+Nix provides a way of shortening these URLs,
+by adding to the [Nix registry][]:
 
 ``` bash
 nix registry add epnix 'github:epics-extensions/epnix'
@@ -27,8 +25,11 @@ For example, the develop command to have EPICS based installed outside of a top
 nix develop epnix
 ```
 
-Another benefit is that you can now initialize an EPNix top by running:
+If you want to initialize an EPNix top,
+you can run:
 
 ``` bash
 nix flake new -t epnix my-top
 ```
+
+  [Nix registry]: https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-registry.html#description