tidy up structure and add migration doc

Author: mr-nick17

GO_EXAMPLE.md

@@ -24,13 +24,9 @@ For `dis-design-system-go` to work correctly, we use `go-bindata` to generate a
 
 Update the frontend service's `Makefile` with the following new commands so that `go-bindata` will generate this file:
 
-:warning: The `APP_RENDERER_VERSION` is unlikely to have been set previously :warning:
-
 ```Makefile
 LOCAL_RENDERER_IN_USE = $(shell grep -c "\"github.com/ONSdigital/dis-design-system-go\" =" go.mod)
 
-APP_RENDERER_VERSION=$(APP_RENDERER_VERSION)
-
 .PHONY: fetch-renderer
 fetch-renderer:
 ifeq ($(LOCAL_RENDERER_IN_USE), 1)
@@ -53,9 +49,9 @@ generate-prod: fetch-renderer
  mv assets/data.go.new assets/data.go
 ```
 
-Due to having distributed assets that are combined with `go-bindata`, we require the `get-renderer-version` and `fetch-renderer-version` tasks to ensure the version of `dp-renderer` as specified in `go.mod` is used.
+Due to having distributed assets that are combined with `go-bindata`, we require the `fetch-renderer` task to ensure the version of `dis-design-system-go` is as specified in `go.mod` is used.
 
-The existing `build` and `debug` tasks should then be updated to use the relevant `generate-` command as a prerequisite:
+The `build` and `debug` tasks should use the relevant `generate-` command as a prerequisite:
 
 ```Makefile
 .PHONY: build
@@ -67,8 +63,6 @@ debug: generate-debug
 
 ## Config
 
-:warning: The `RendererVersion` is unlikely to have been set previously :warning:
-
 `config.go` should be updated to include four properties: `PatternLibraryAssetsPath`, `SiteDomain`, `Debug` and `RendererVersion`.
 
 You will also need to add additional logic to `config.go` to handle the path for pattern library assets when running `make debug` or the published assets in a `prod` build.
@@ -128,7 +122,7 @@ func get() (*Config, error) {
 
 You will need the `RenderClient` interface in order to implement the methods that `dis-design-system-go` exposes.
 
-```golang
+```go
 type RenderClient interface {
   BuildPage(w io.Writer, pageModel interface{}, templateName string)
   NewBasePageModel() model.Page
@@ -139,7 +133,7 @@ type RenderClient interface {
 
 Example handler:
 
-```golang
+```go
 func getCookiePreferencePage(w http.ResponseWriter, rendC RenderClient, cp cookies.Policy, isUpdated bool, lang string) {
   // create a new base page model that inject SiteDomain and PatternLibraryAssetsPath into the page struct
   basePage := rendC.NewBasePageModel()
@@ -149,13 +143,14 @@ func getCookiePreferencePage(w http.ResponseWriter, rendC RenderClient, cp cooki
 
   // send the mapped data, with ResponseWriter and template name defined by the actual template file name (e.g. cookies-preferences.tmpl) to the render lib
   rendC.BuildPage(w, m, "cookies-preferences")
+}
 ```
 
 ## Mappers
 
 Example mapper:
 
-```golang
+```go
 import (
   "dp-frontend-cookie-controller/model"
 
@@ -172,11 +167,11 @@ func CreateCookieSettingPage(basePage core.Page, policy cookies.Policy, isUpdate
 }
 ```
 
-### Rendering error pages
+## Rendering error pages
 
-We use a HTTP middleware handler to intercept error status in our controllers then call `BuildErrorPage` to render an error page. To set up the middleware we use [Alice](https://github.com/justinas/alice) when instantiating the router in our controllers. See [README](/README.md#instantiation) for setting up the render client that we pass to the middleware.
+We use a HTTP middleware handler to intercept error status in our controllers then call `BuildErrorPage` to render an error page. To set up the middleware we use [Alice](https://github.com/justinas/alice) when instantiating the router in our controllers.
 
-```golang
+```go
 import "github.com/ONSdigital/dis-design-system-go/middleware/renderror"
 
 middleware := []alice.Constructor{

MIGRATION.md

@@ -0,0 +1,67 @@
+# Migration
+
+This guide assumes you are using an app that currently consumes `dp-design-system` and `dp-renderer`.
+
+From within your consuming frontend service:
+
+1. Get the go module:
+
+    ```shell
+    go get github.com/ONSdigital/dis-design-system-go
+    ```
+
+1. Find and replace statements that relate to `dp-renderer` and replace with `dis-design-system-go` in `.go` files and the `Makefile`
+
+    e.g.
+  
+    ```diff
+    - "github.com/ONSdigital/dp-renderer/v2/model"
+    + "github.com/ONSdigital/dis-design-system-go/model"
+    ```
+
+1. Add the `APP_RENDERER_VERSION` into the `build` and `debug` Makefile targets
+
+    For example the `debug` target might look similar to:
+  
+    ```Makefile
+    .PHONY: debug
+    debug: generate-debug
+        go build -tags 'debug' -race -o $(BINPATH)/dp-frontend-homepage-controller -ldflags "-X main.BuildTime=$(BUILD_TIME) -X main.GitCommit=$(GIT_COMMIT) -X main.Version=$(VERSION)"
+        HUMAN_LOG=1 DEBUG=1 APP_RENDERER_VERSION=$(APP_RENDERER_VERSION) $(BINPATH)/dp-frontend-homepage-controller
+    ```
+
+1. Retrieve the environment variable `APP_RENDERER_VERSION` that you have set in the previous step and expose it in `config.go`.
+
+    Change the s3 directory to `dis-design-system-go`.
+
+    ```go
+    type Config struct {
+        // Other config here
+        RendererVersion string `envconfig:"APP_RENDERER_VERSION"`
+    }
+
+    func get() (*Config, error) {
+        if cfg != nil {
+            return cfg, nil
+        }
+
+        // other code
+
+        cfg = &Config{
+            // Some other default config here
+            RendererVersion: "v0.1.0", // OPTIONALLY - set to a stable base
+        }
+
+        // other code 
+
+        if cfg.Debug {
+            cfg.PatternLibraryAssetsPath = "http://localhost:9002/dist/assets"
+        } else {
+            cfg.PatternLibraryAssetsPath = fmt.Sprintf("//cdn.ons.gov.uk/dis-design-system-go/%s", cfg.RendererVersion)
+        }
+
+        // other code
+    }
+    ```
+
+1. Test your changes by running `make debug` from the consuming app. Follow the steps in the [README](README.md#generate-the-css-and-js) to generate the css/js locally.

README.md

@@ -6,6 +6,8 @@ Beta rendering library for Dissemination frontend go microservices. `dis-design-
 
 * Run `make help` to see full list of make targets
 
+## CSS/JS
+
 ### Install dependencies
 
 To build, run, deploy, test and audit the app you will need some additional tooling:
@@ -50,11 +52,11 @@ No further dependencies other than those defined in `go.mod`
 
 * Once built, you can find assets stored on the web server, default location is [localhost:9002/dist/assets/](http://localhost:9002/dist/assets/)
 
-### Go library
+## Go library
 
 `dis-design-system-go` also acts as a Go library which contains template helpers, model structs and components that can be used by the consuming frontend app to serve HTML consistently across the ONS website. To make use of the `go` rendering, you will need to install it within your `go` frontend app.
 
-#### Installation
+### Installation
 
 Other than `dis-design-system-go` itself, you will need a utility that can combine service-specific and `dis-design-system-go` assets. We currently use `go-bindata` for this process. From the consuming frontend app, run the following commands to install:
 
@@ -64,49 +66,24 @@ Other than `dis-design-system-go` itself, you will need a utility that can combi
 
 * `go-bindata`: `go get github.com/kevinburke/go-bindata`
 
-#### Instantiation
-
-Assuming you have `go-bindata` set up to generate the relevant asset helper functions, you can instantiate the renderer with a default client (in this case, the default client is [`unrolled`](https://github.com/unrolled/render)).
-
-```go
-rend := render.NewWithDefaultClient(asset.Asset, asset.AssetNames, cfg.PatternLibraryAssetsPath, cfg.SiteDomain)
-```
-
-You can also instantiate a `Render` struct without a default client by using `New()`. This requires a rendering client that fulfills the `Renderer` interface to be passed in as well.
-
-```go
-rend := render.New(rendereringClient, patternLibPath, siteDomain)
-```
-
-#### Mapping data and building a page
-
-When mapping data to a page model, you can use `NewBasePageModel` to instantiate a base page model with its `PatternLibraryAssetsPath` and `SiteDomain` properties auto-populated via the `Render` struct:
-
-```go
-basePage := rendC.NewBasePageModel()
-mappedPageData := mapper.CreateExamplePage(basePage)
-```
+* No further dependencies other than those defined in `go.mod`
 
-In order to generate HTML from a page model and template, use `BuildPage`, passing in the `ResponseWriter`, mapped data, and the name of the template:
-
-```go
-rend.BuildPage(w, mappedPageData, "name-of-template-file-without-extension")
-```
+## Worked example
 
-If an error occurs during page build, either because of an incorrect template name or incorrect data mapping, `dp-renderer` will write an error via an `errorResponse` struct.
+See the [go example](GO_EXAMPLE.md) guide for an example implementation.
 
 ## Using design patterns or components in your service
 
 See [PATTERNS](PATTERNS.md) for details.
 
-## Worked example
-
-See the [go example](GO_EXAMPLE.md) guide for a worked example. This guide can also be used to support migrating from `dp-renderer` and `dp-design-system` to `dis-design-system-go`.
-
 ## Contributing
 
 See [CONTRIBUTING](CONTRIBUTING.md) for details.
 
+## Migrating
+
+See [MIGRATION](MIGRATION.md) for details on how to migrate from `dp-design-system` and `dp-renderer` to the `dis-design-system-go`.
+
 ## License
 
 Copyright © 2025, Office for National Statistics (<https://www.ons.gov.uk>)