add manifest and docker info

docs/explanations/changes.md

@@ -0,0 +1,87 @@
+Change Management Manifesto
+===========================
+
+Pledge
+------
+
+This page represents a pledge to control breaking changes for users of `epics-containers`. The framework is still under development and there still may be breaking changes in future updates. However we now have a mechanism in place to allow users to adopt the framework, take advantage of the current features and then accept future updates in a controlled fashion.
+
+From version 3.4.0 onwards we will endeavour to make changes in a controlled fashion that obeys SemVer 2.0.0 rules. We will also try to ensure that it is possible to apply updates in a gradual manner and not require a blanket update.
+
+The [](../reference/changelog.md) will give details of any things to be aware of between versions, including minor version updates.
+
+Dependency Matrix
+-----------------
+
+Users of the framework will develop two kinds of repository:
+
+|     |     |
+| --- | --- |
+| Beamline repo | A beamline or other grouping of IOC instance descriptions |
+| Generic IOC repo | A definition of a generic IOC container image for a particular class of device |
+
+Both of these types of repository are initially created using a copier template. The copier template version will have a SemVer version number that determines which component versions it is compatible with.
+
+Any breaking changes to the framework will be made in a new Major version of the framework and hence a new Major version of the copier templates.
+
+The following diagram shows the set of components that are involved in the framework and the relationships between them. The dependencies between these components are not a strict API and the diagram attempts to highlight the features of each component that affect other components.
+
+The diagram may be used by developers of the framework to plan how changes will be made and to ensure that breaking changes are made in a controlled manner.
+
+Users of the framework are only concerned with the top two boxes and these are always updated on an as-needed basis via the copier templates.
+
+:::{figure} ../images/dependency_matrix.png
+`epics-containers` dependency matrix
+:::
+
+All `ec` SemVer components will always have their major version bumped simultaneously. Likewise for `ibek` SemVer components. These are at versions 3.4.0 and 2.0.0 respectively at the time of writing.
+
+
+Updating user projects
+----------------------
+
+A repository that was originally created using a copier template can be updated to a new version using the following command (assumes you have an active python venv with copier installed):
+
+```bash
+copier update -r VERSION_NUMBER --trust .
+```
+
+You can supply the VERSION_NUMBER of the template you want or omit the -r option to get the latest released version.
+
+This will update your project in place. You should then inspect the changes using git (the source control pane in vscode is excellent for this purpose) and commit them to your repository.
+
+When a beamline repository is updated, it is still possible to deploy old versions of its IOC instances, even with a major version difference. That is because the deploy mechanism makes a temporary clone of the beamline repository and deploys the instance described in that version.
+
+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.
+
+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.
+
+### ibek
+
+
+Changes to the CLI commands inside of the container build/runtime are initiated in the `ibek` python module that lives inside every generic IOC. This can affect the support module build recipes in `ibek-support` and potentially the Dockerfile in Generic IOC projects.
+
+### ec-helm-charts
+
+Changes here affect how IOCs and other services are deployed into Kubernetes. These would likely affect beamline repositories as they contain the versions of Helm Charts used to deploy their instances. Potentially changes to these Charts may require an update to the edge-services-cli to support new features.
+
+### ioc-template
+
+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` 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.
+
+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/reference/changelog.md

@@ -0,0 +1,29 @@
+Change Log
+==========
+
+Each individual repository in the `epics-containers` GitHub Organization will have its own changelog. This page is intended for users of `epics-containers` who are adopting the next versions of the templates into their services projects or generic IOC projects. See [](../explanations/changes) for a discussion of how changes are managed in this framework.
+
+blxxi-ea-test-01
+----------------
+
+The `ec-services-template` creates beamline (or other IOC grouping) repostories that initially contain an example IOC and set of essential services. The example IOC will be called `blxxi-ea-test-01` and could be used to deploy a sim-detector.
+
+It is quite useful to keep this example because if you do so it can be used to easily see what changes to each IOC instance might need to be made. The copier template will attempt to update all your own IOC Instances. But the reliable way to keep them up to date is to verify that they have the same changes as the example.
+
+Such changes will be rare but it just happens that 3.4.0 is an example of this. See below.
+
+April 2024 - templates 3.4.0
+----------------------------
+
+### ioc-template and ec-services-template
+
+- `dependabot.yaml` no longer looks for changes in docker or python dependencies from your ioc-xxx projects. The philosophy here is that all dependency updates should happen in a controlled manner via the copier update mechanism. TODO: it would be good to have dependabot monitor the copier template updates, but this is not currently possible.
+
+### ioc-template
+
+- The significant change here is that the CI is now multi target and supports cross compilation to RTEMS-beatnik as well as native linux x86. The template has a new question that asks if you want RTEMS support, you should select no unless your Generic IOC is intended for this target architecture.
+
+
+### ec-services-template
+
+- The mechanism by which the configmap of each IOC's config folder has changed. It now requires that there is a `templates` folder in each IOC instance folder that is a soft link to ../../include/ioc/templates. Although the template includes a migration script that is supposed to do this, it has not always proved to work. To create these folders yourself, the easiest way is to copy and paste from the blxxi-ea-test-01 IOC instance.

docs/reference/docker.md

@@ -0,0 +1,18 @@
+Working with Docker
+===================
+
+DLS is a `podman` shop and therefore more testing is done with `podman` than `docker` as the container CLI used with developer containers. `podman` works extremely well with developer containers, but `docker` needs a little more work sometimes.
+
+We do fully support `docker`, please report any issues you find.
+
+There are a few things to know if you are using `docker` in your developer containers:
+
+1. add `export EC_REMOTE_USER=vscode` into your `~/.bashrc` or `~/.bash_profile`. The epics-containers devcontainer.json files will use this to set the account that your user will use inside devcontainers.
+1. you may need to tell git that you are ok with the repository permissions. `vscode` may ask you about this or you may need to do the command:
+    ```bash
+    git config --global --add safe.directory <Git folder>
+    ```
+1. you can use `sudo` if you are having permissions issues. In particular the following will reset permissions on a folder:
+    ```bash
+    sudo chown -r vscode <folder>
+    ```

docs/tutorials/setup_workstation.md

@@ -69,8 +69,7 @@ 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.
 
-If you are using docker, simply replace `podman` with `docker` in the
-commands listed in these tutorials.
+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)
 
 The podman version required is 4.0 or later. Any version of docker since 20.10
 will also work. Pick the tool that has the most recent version for your platform.