Merge pull request #98 from minijackson/doc-release-branches

Document release branches

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/tutorials/integration-tests.md

@@ -6,7 +6,7 @@ title: Integration tests
 
 Through the [NixOS testing framework], EPNix provides a way of specifying a machine configuration, and running a Python script that can do various kind of testing.
 
-If you created your IOC using the EPNix template, like suggested in the [Getting Started] documentation, you will see a `checks/` directory.
+If you created your IOC using the EPNix template, like suggested in the [StreamDevice tutorial], you will see a `checks/` directory.
 This directory should contain the integration tests you want to run.
 
 To add an integration test to EPNix, record it in your `flake.nix` under the `epnix.checks.files` option.
@@ -43,7 +43,7 @@ For an overview of what you can input in the machine configuration, please refer
 You can also read about the Python test script API [here][NixOS testing framework].
 
   [NixOS testing framework]: https://nixos.org/manual/nixos/stable/index.html#sec-nixos-tests
-  [Getting Started]: ./getting-started.md
+  [StreamDevice tutorial]: ./streamdevice.md
   [NixOS documentation]: https://nixos.org/manual/nixos/stable/index.html#sec-configuration-syntax
 
 # Starting your IOC through systemd
@@ -115,7 +115,6 @@ You can also look at examples either in the EPNix repository under the [`checks`
 ```
 
   [here]: https://search.nixos.org/options?channel=21.11&from=0&size=50&sort=alpha_asc&type=packages&query=systemd.services.
-  [epics-systemd]: https://github.com/minijackson/epics-systemd
   [Packaging Python scripts]: ../guides/testing/packaging-python-scripts.md
   [NixOS tests documentation]: https://nixos.org/manual/nixos/stable/index.html#sec-nixos-tests
   [`checks` folder]: https://github.com/epics-extensions/epnix/tree/master/checks

doc/nixos/guides/_pre-requisites.md

@@ -18,8 +18,8 @@ For example:
 ``` {.diff filename="flake.nix"}
  {
    # ...
-+  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.11";
-+  inputs.epnix.url = "github:epics-extensions/EPNix";
+   inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.11";
++  inputs.epnix.url = "github:epics-extensions/EPNix/nixos-23.11";
 
    # ...
    outputs = {

doc/nixos/tutorials/archiver-appliance.md

@@ -58,7 +58,7 @@ Fill the file with these lines:
   description = "Configuration for running Archiver Appliance in a VM";
 
   inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.11";
-  inputs.epnix.url = "github:epics-extensions/EPNix";
+  inputs.epnix.url = "github:epics-extensions/EPNix/nixos-23.11";
 
   outputs = { self, nixpkgs, epnix }: {
     nixosConfigurations.nixos = nixpkgs.lib.nixosSystem {

templates/top/flake.nix

@@ -2,7 +2,7 @@
   description = "EPICS IOC for <...>";
 
   inputs.flake-utils.url = "github:numtide/flake-utils";
-  inputs.epnix.url = "github:epics-extensions/epnix";
+  inputs.epnix.url = "github:epics-extensions/epnix/nixos-23.11";
 
   # If you have a support module as a separate EPNix repository,
   # add it as an input here:
@@ -80,35 +80,34 @@
     # ---
     # "x86_64-linux" should still be specified so that the development
     # environment can be built on your machine.
-    flake-utils.lib.eachSystem ["x86_64-linux"] (system:
-      with epnix.lib; let
-        epnixDistribution = evalEpnixModules {
-          nixpkgsConfig = {
-            # This specifies the build architecture
-            inherit system;
-
-            # This specifies the host architecture, uncomment for cross-compiling
-            #
-            # The complete of example architectures is here:
-            # https://github.com/NixOS/nixpkgs/blob/nixos-22.11/lib/systems/examples.nix
-            # ---
-            #crossSystem = epnix.inputs.nixpkgs.lib.systems.examples.armv7l-hf-multiplatform;
-          };
-          epnixConfig = myEpnixConfig;
+    flake-utils.lib.eachSystem ["x86_64-linux"] (system: let
+      epnixDistribution = epnix.lib.evalEpnixModules {
+        nixpkgsConfig = {
+          # This specifies the build architecture
+          inherit system;
+
+          # This specifies the host architecture, uncomment for cross-compiling
+          #
+          # The complete of example architectures is here:
+          # https://github.com/NixOS/nixpkgs/blob/nixos-22.11/lib/systems/examples.nix
+          # ---
+          #crossSystem = epnix.inputs.nixpkgs.lib.systems.examples.armv7l-hf-multiplatform;
+        };
+        epnixConfig = myEpnixConfig;
+      };
+    in {
+      packages =
+        epnixDistribution.outputs
+        // {
+          default = self.packages.${system}.build;
         };
-      in {
-        packages =
-          epnixDistribution.outputs
-          // {
-            default = self.packages.${system}.build;
-          };
 
-        inherit epnixDistribution;
+      inherit epnixDistribution;
 
-        devShells.default = self.packages.${system}.devShell;
+      devShells.default = self.packages.${system}.devShell;
 
-        checks = epnixDistribution.config.epnix.checks.derivations;
-      })
+      checks = epnixDistribution.config.epnix.checks.derivations;
+    })
     // {
       overlays.default = final: prev:
         self.epnixDistribution.x86_64-linux.generatedOverlay final prev;