Skip to content

Latest commit

 

History

History
90 lines (60 loc) · 3.51 KB

README.adoc

File metadata and controls

90 lines (60 loc) · 3.51 KB
Raw

Release Notes for SUSE CaaS Platform

You can view these release notes in two ways:

Contributing

Want to help? We love to hear that! Below are a few hints to guide you.

Writing

These release notes are written in the AsciiDoc (*.adoc) format. For some great AsciiDoc documentation, see https://asciidoctor.org/docs/asciidoc-writers-guide/.

Updating Content

  1. Fork this repository.

  2. Make the intended changes. (Make sure to read Keeping the GitHub/GitLab Preview of These Release Notes Intact.)

  3. Validate and build a test version (see below for more details)

  4. Submit the changes as a pull request

Building the Release Notes Documents

The final version for the product is build in the SUSE Build Service.

For validation and test purposes follow the steps below:

  1. Install the DocBook Authoring and Publishing Suite (daps) package from the Documentation:Tools openSUSE Build Service project.

  2. Use the make to build all required documents. For a single HTML document, for example make single-html.

  3. Alternatively, you can run the following command, which will build the documentation in your local folder, with the help of a container similar to what is used in our CI: docker run -v ./:/usr/src/app -w /usr/src/app susedoc/ci:openSUSE-42.3 make single-html

Keeping the GitHub/GitLab Preview of These Release Notes Intact

The GitHub/GitLab preview mode is handy but comes with a couple of snags compared to the build of the release notes that is used for the SUSE Web site:

  • GitHub/GitLab will simply render a preview of a single *.adoc file using AsciiDoctor’s built-in HTML conversion. GitHub/GitLab previews do not support embedding one AsciiDoc file in another, you can only use links between them.

  • The SUSE Web site build combines multiple *.adoc files into a single HTML output file. It is based on AsciiDoctor’s AsciiDoc-to-DocBook-XML conversion, the result of which is then further converted into HTML/PDF using DAPS and the DocBook XSL stylesheets.

For this reason, the central file adoc/MAIN.release-notes.adoc contains somewhat unsightly ifdef/ifndef blocks that check whether the file is displayed in the GitHub/GitLab preview, switching between using links to other files for GitHub/GitLab and include:: statement in all other cases.

The issue of not being able to embed other AsciiDoc files when using the GitHub/GitLab preview also affects the "attribute entries" file adoc/entities.adoc. Attribute entries allow easily referencing text used multiple (similar to entities in XML). Hence, for the GitHub/GitLab preview, each file contains a copy of the entire attribute entry file at the top. When updating attribute entries, always make sure to:

  1. Edit adoc/entities.adoc first (these are used for the regular build)

  2. Run make update-entries to update the dependent attribute entries in each of the *.adoc files (these are used for GitHub/GitLab previews).

Updating the Release Notes on the Website

The website is automatically updated when we release a new version of the release-notes-caasp package as maintenance update.