review of changes manifesto

Author: gilesknap

docs/explanations/changes.md

@@ -55,15 +55,15 @@ When a beamline repository is updated, it is still possible to deploy old versio
 User Project Versioning
 -----------------------
 
-The documentation has recommended using DateVer for beamline repos and generic IOC repos. This is because both types of repo have many parts with different version schemes so SemVer is not really applicable. DateVer is not required and you  are free to use any scheme you wish for these repositories.
+The documentation has recommended using DateVer for beamline repos and generic IOC repos. This is because SemVer is not really applicable to these. However, DateVer is not required and you are free to use any scheme you wish for these repositories.
 
 It is easy to determine which template version and thus which `ec` SemVer version your repository was last updated from. Inspect the file `.copier_answers.yml` in the root of your repository. This file contains the version of the template that was used to create the repository in the field `_commit`.
 
 
 Types of Changes
 ----------------
 
-Changes to the framework are likely to be initiated in one of three places in the described under the following headings. As far as possible such changes will be backwards compatible going forward, and if they are not then a major version release will be made.
+Changes to the framework are likely to be initiated in one the places described under the following headings. As far as possible such changes will be backwards compatible going forward, and if they are not then a major version release will be made.
 
 ### ibek
 
@@ -79,9 +79,8 @@ Changes here affect how IOCs and other services are deployed into Kubernetes. Th
 The Generic IOC template is well established and stable. However, each time a new target architecture is added, this will need updates to the CI. We will be supporting Windows and ARM targets in future. These changes should certainly be backwards compatible and not affect existing projects.
 
 
-ibek-support
-------------
+### ibek-support
 
-`ibek-support` is a unique project in that it is a submodule of all Generic IOCs. It is expected that there will be constant change to this module as new support modules are added. However, such changes will almost entirely be adding new folders and not affect existing generic IOCs. We encourage users to fork this repository, add their own support modules and submit PRs back to the original so that a wide range of support modules can be shared.
+`ibek-support` is a unique project in that it is a submodule of all Generic IOCs. It is expected that there will be constant change to this module as new support modules are added. However, such changes will almost entirely be adding new folders and not affect existing generic IOCs. We encourage users to fork this repository, add their own support modules and submit PRs back to the original so that a wide range of support modules can be shared (a branch rather than fork is preferred for internal developers).
 
 If there is a need to change the CLI that ibek-support uses, then a new version of `ibek` will be released. Only generic IOCs that have been updated to pick up the new version of `ibek` would be able to use these changes. Because older generic IOCs will retain the old commit of the 'ibek-support' submodule, they will not be affected by the changes until they are updated.

docs/how-to/own_tools.md

@@ -17,5 +17,6 @@ epics-containers has been tested with
 - vscode
 - Github Codespaces
 
-TODO: add instructions for using other editors. Potentially we could enhance
-the epics-containers-cli to support other editors with minimal effort.
+If you prefer console based editors like vim or emacs, then you will get the best results by launching the development containers defined in the epics-containers using the devcontainer CLI as described here <https://containers.dev/supporting#devcontainer-cli>.
+
+In addition you could install your editor inside the developer container by adding an apt-install command into the `epics-containers` user personalization file. See [details here](https://github.com/epics-containers/epics-containers.github.io/blob/3a87e808e1c7983430a30c5a4dcd0d0661895d60/.devcontainer/postCreateCommand#L23-L27)

docs/images/dependency_matrix.png

@@ -12,7 +12,7 @@ and c is the class of beamline.
 
 :::{note}
 You may choose your own naming convention, but lower case letters,
-numbers and hyphens only are recommended for both domain names and
+numbers and hyphens only are required for both domain names and
 IOC names. This is a restriction that helm introduces for package names.
 :::
 

docs/tutorials/create_beamline.md

@@ -6,7 +6,7 @@ The tools you need to install are:
 
 - Visual Studio Code
 - a container platform, either podman or docker
-- Python 3.10 or later + a Python virtual environment
+- Python 3.11 or later + a Python virtual environment
 - git client for version control
 
 Visual Studio Code is recommended because it has excellent integration with
@@ -61,13 +61,12 @@ devcontainer in the next tutorial.
 ### Setup Docker or Podman
 
 :::{Note}
-**DLS Users**: RHEL 8 Workstations at DLS have podman 4.4.1 installed by default.
+**DLS Users**: RHEL 8 Workstations at DLS have podman 4.6.1 installed by default.
 RHEL 7 Workstations are not supported.
 :::
 
 Next install docker or podman as your container platform. epics-containers
-has been tested with podman 4.4.1 on RedHat 8, and Docker 24.0.5 on
-for Ubuntu 22.04.
+has been tested with podman 4.4.1 and higher on RedHat 8, and Docker 24.0.5 and higher on for Ubuntu 22.04 and higher.
 
 If you are using docker, simply replace `podman` with `docker` in the commands listed in these tutorials. `docker` users should also take a look at this page: [](../reference/docker.md)