From c7dd4ab46f07575dcb2b228f9febb9d6b3b18ba2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Such=C3=A1nek?= Date: Tue, 25 Jun 2024 19:40:50 +0200 Subject: [PATCH] Document archiving previous releases; RHELDOCS-18441 --- ...s-releases-in-one-continuous-document.adoc | 54 +++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 docs/modules/proc_publishing-previous-releases-in-one-continuous-document.adoc diff --git a/docs/modules/proc_publishing-previous-releases-in-one-continuous-document.adoc b/docs/modules/proc_publishing-previous-releases-in-one-continuous-document.adoc new file mode 100644 index 0000000..0964b5f --- /dev/null +++ b/docs/modules/proc_publishing-previous-releases-in-one-continuous-document.adoc @@ -0,0 +1,54 @@ +:_newdoc-version: 2.18.2 +:_template-generated: 2024-06-25 +:_mod-docs-content-type: PROCEDURE + +[id="publishing-previous-releases-in-one-continuous-document_{context}"] += Publishing previous releases in one continuous document + +As a release notes maintainer, you can publish several releases or all release history in one document. Only the latest release is actively generated by `acorns`, while the previous releases are archived as manual content. You can see an example of a similar setup in the link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/8/html/8.2_release_notes/rhel-8_2_1_release#new_features[RHEL 8.2 release notes]. + +.Prerequisites + +* You have a working `acorns` configuration in a Git repository, later called the _source repository_. +* A CI/CD pipeline runs `acorns` and saves the generated content in a separate, _generated repository_. ++ +If you do not use this workflow, you can still archive previous releases in one document, but the procedure is slightly different. + +.Procedure + +. Generate your release notes for the current release as usual. + +. When the current release is published and done, you can archive it. + +. Open your generated RN repository. + +. Navigate to the `external` branch of the current release. + +. Download the latest generated files. + +. In your source directory, create a new directory under the `manual-content/` directory. Name it such that it refers to the release that you are archiving: for example, `manual-content/RHOSO-18.0-Beta/`. + +. Move all the downloaded generated files into the newly created directory in your source repository. + +. In the same directory, create a `main.adoc` assembly. Set a title that refers to the archived version, such as _RHOSO 18.0 Beta_. + +. In the assembly, include all the downloaded generated files. ++ +Because you are including files in the same directory, specify only the file names with no directory path in the include directives. + +. Include the new assembly from your master file, such as the `master_-_template.adoc` file. For example: ++ +[subs="quotes"] +---- +\include::manual-content/__RHOSO-18.0-Beta__/main.adoc[leveloffset=+1] +---- + +. You now have a _RHOSO 18.0 Beta_ chapter in your RN document that includes all release notes for that specific release, saved as static, manual content that originated from the generated repository. + +. As `acorns` regenerates new release notes, they work towards the following release. In your master file, they are included from the `acorns/generated/` directory, until you want to archive this release as a another static assembly. + +. Optional: If you want your current, actively generated release to also appear in a separate chapter of the document: +.. Create a new assembly with a title appropriate to the current release. +.. Move the include directives that refer to `acorns/generated/` from your master file to the new assembly. +.. Include the new assembly in your master file. +