From 62593398d3df73b9e525d9bfd323470c86a97fe1 Mon Sep 17 00:00:00 2001
From: Adrian Clay Lake <clay.lake@canonical.com>
Date: Tue, 23 Jul 2024 16:25:10 +0200
Subject: [PATCH] docs: fix tutorial on how to create a package slice for
 chisel (#648)

* fix(docs/how-to/code/create-slice/openssl.yaml): updated tutorial openssl.yaml from chisel-releases to fix missing slice

* fix(docs/how-to/chisel/create-slice.rst): updated tutorial create-slice.rst to reflect new example openssl.yaml

* Update docs/how-to/chisel/create-slice.rst

Co-authored-by: Cristovao Cordeiro <cristovao.cordeiro@canonical.com>

* fix(docs/how-to/chisel/create-slice.rst): suggestion broke line limit in linter

---------

Co-authored-by: Cristovao Cordeiro <cristovao.cordeiro@canonical.com>
---
 docs/how-to/chisel/create-slice.rst        | 21 ++++++----
 docs/how-to/code/create-slice/openssl.yaml | 45 ++++++++++++++--------
 2 files changed, 43 insertions(+), 23 deletions(-)

diff --git a/docs/how-to/chisel/create-slice.rst b/docs/how-to/chisel/create-slice.rst
index 07175e8bf..95a0b8f58 100644
--- a/docs/how-to/chisel/create-slice.rst
+++ b/docs/how-to/chisel/create-slice.rst
@@ -129,13 +129,17 @@ Create a new YAML file named ``openssl.yaml``, with the following content:
 .. literalinclude:: ../code/create-slice/openssl.yaml
     :language: yaml
 
-Notice the unforeseen new slice ``config``. Because your OpenSSL binaries depend
-on the OpenSSL configuration files, and those were not yet present anywhere in
-the Chisel releases upstream, you also need to create that slice! You may also
-ask **"why not put those configuration files inside the "bins" slice"**? You
-could! But we recommend, as a best practice, to separate and group contents
-according to their nature, as you may tomorrow need to create a new slice
-definition that only needs the OpenSSL configurations and not the binaries.
+Notice the additional new slices ``config``, ``data`` and ``copyright``. The
+OpenSSL package includes files other than binaries, some of these files may be
+required depending on the specific use of OpenSSL. It is beneficial to separate
+and group the contents of a package according to their nature, allowing
+developers to select only the files they require. For example, one developer may
+require the ``bins`` and ``config`` slices of a package, while another only
+requires the ``config`` slice as a dependency of another package. Our
+`contribution guidelines`_ provides more details on best practices for creating
+new slices.
+
+
 
 And that's it. This is your brand new slice definitions file, which will allow
 Chisel to install **just** the OpenSSL binaries (and their dependencies) into
@@ -148,3 +152,6 @@ publish it upstream for others to use, please check the following guides.
   https://github.com/canonical/chisel-releases/blob/ubuntu-22.04/slices/libc6.yaml
 .. _libssl3:
   https://github.com/canonical/chisel-releases/blob/ubuntu-22.04/slices/libssl3.yaml
+.. _contribution guidelines:
+  https://github.com/canonical/chisel-releases/blob/main/CONTRIBUTING.md
+
diff --git a/docs/how-to/code/create-slice/openssl.yaml b/docs/how-to/code/create-slice/openssl.yaml
index 3de2ff4b0..5d5506232 100644
--- a/docs/how-to/code/create-slice/openssl.yaml
+++ b/docs/how-to/code/create-slice/openssl.yaml
@@ -1,19 +1,32 @@
 package: openssl
+
+essential:
+  - openssl_copyright
+
 slices:
-    bins:
-        essential:
-          - libc6_libs
-          - libc6_config
-          - libssl3_libs
-          - openssl_config
-        contents:
-            /usr/bin/c_rehash:
-            /usr/bin/openssl:
+  bins:
+    essential:
+      - libc6_config
+      - libc6_libs
+      - libssl3_libs
+      - openssl_config
+    contents:
+      /usr/bin/c_rehash:
+      /usr/bin/openssl:
+
+  config:
+    contents:
+      /etc/ssl/certs/:
+      /etc/ssl/openssl.cnf:
+      /etc/ssl/private/:
+      /usr/lib/ssl/certs:
+      /usr/lib/ssl/openssl.cnf:
+      /usr/lib/ssl/private:
+
+  data:
+    contents:
+      /usr/lib/ssl/cert.pem: {symlink: /etc/ssl/certs/ca-certificates.crt}
 
-    config:
-        contents:
-            /etc/ssl/private/:
-            /etc/ssl/openssl.cnf:
-            /usr/lib/ssl/certs:
-            /usr/lib/ssl/openssl.cnf:
-            /usr/lib/ssl/private:
+  copyright:
+    contents:
+      /usr/share/doc/openssl/copyright: