Bumping version: 0.17.0 → 0.18.0 (#249)

* Bump version
* Create changelog entry
* Slightly rearrange the steps in the "Create a New Release"
  section of the Developer Guide.
* Add an additional step in the "Building Documentation" section
  to watch for warnings and errors.

Author: tomschr

CHANGELOG.rst

@@ -21,6 +21,83 @@ Changes for the upcoming release can be found in the
 
 .. towncrier release notes start
 
+Version 0.18.0
+==============
+
+Bug Fixes
+---------
+
+- Fixed the ``config`` subcommand to prevent crashes when displaying help (``-h/--help``) with an invalid configuration file. The ``app`` and ``env`` subcommands have been unified into ``config list`` and ``config validate`` for a more streamlined user experience. (:gh:`112`)
+- Improved error handling for configuration loading. Malformed TOML files now trigger a formatted diagnostic message with line and column details instead of a Python traceback. (:gh:`175`)
+- Added strict syntax validation for configuration placeholders. The application will now explicitly report an error and halt when encountering malformed placeholders (e.g., missing or incorrectly ordered curly braces like ``{server.name``) instead of silently leaving them unresolved. (:gh:`233`)
+
+
+Improved Documentation
+----------------------
+
+- Describe the new portal schema from the perspective of a user trying to add
+  or change the config.
+  Additionally, rework on the glossary page to improve the layout and readability of terms and definitions. (:gh:`238`)
+- Improve usability and readability of docs by adding
+  homepage navigation cards using Sphinx Design extension. (:gh:`247`)
+
+
+Infrastructure
+--------------
+
+- Several dependency updates:
+
+  * `Update pytest-cov requirement from >=6.1.1 to >=7.1.0 <https://github.com/openSUSE/docbuild/pull/244>`_
+  * `Update sphinx-autodoc-typehints requirement from >=3.2.0 to >=3.10.2 <https://github.com/openSUSE/docbuild/pull/243>`_
+  * `Update sphobjinv requirement from >=2.3.1.3 to >=2.4 <https://github.com/openSUSE/docbuild/pull/242>`_
+  * `Update sphinx requirement from >=8.2.3 to >=9.1.0 <https://github.com/openSUSE/docbuild/pull/241>`_
+  * `Update pydata-sphinx-theme requirement from >=0.16.1 to >=0.17.1 <https://github.com/openSUSE/docbuild/pull/240>`_
+  * `Update sphinx-autoapi requirement from >=3.6.0 to >=3.8.0 <https://github.com/openSUSE/docbuild/pull/229>`_
+  * `Update towncrier requirement from >=24.8.0 to >=25.8.0 <https://github.com/openSUSE/docbuild/pull/228>`_
+  * `Update pydantic requirement from >=2.11.4 to >=2.13.3 <https://github.com/openSUSE/docbuild/pull/227>`_
+  * `Update tomlkit requirement from >=0.13.2 to >=0.14.0 <https://github.com/openSUSE/docbuild/pull/226>`_
+  * `Update rich requirement from >=14.0.0 to >=15.0.0 <https://github.com/openSUSE/docbuild/pull/225>`_
+  * `Bump softprops/action-gh-release from 2 to 2.6.2 <https://github.com/openSUSE/docbuild/pull/219>`_
+  * `Update pyright requirement from >=1.1.401 to >=1.1.408 <https://github.com/openSUSE/docbuild/pull/218>`_
+  * `Update setuptools requirement from >=77 to >=82.0.1 <https://github.com/openSUSE/docbuild/pull/217>`_
+  * `Update ruff requirement from >=0.11.12 to >=0.15.10 <https://github.com/openSUSE/docbuild/pull/216>`_
+  * `Update pytest-asyncio requirement from >=1.0.0 to >=1.3.0 <https://github.com/openSUSE/docbuild/pull/215>`_
+  * `Update docformatter requirement from >=1.7.5 to >=1.7.7 <https://github.com/openSUSE/docbuild/pull/214>`_
+
+
+Code Refactoring
+----------------
+
+- Refactor product schema (:pr:`197`)
+
+  These changes reflect broad architectural shifts and naming conventions
+  throughout the entire configuration system.
+
+  * **Rebranding**: The naming convention has shifted from Docserv to Portal.
+    This is reflected in namespace changes and element renaming
+    (e.g., ``<product>`` is now part of a portal root).
+
+  * **Documentation-First Design**: The schema now heavily utilizes ``db:refname``
+    and ``db:refpurpose`` annotations for almost every element and attribute.
+    This allows for automated generation of human-readable documentation directly
+    from the RNC file.
+
+  * **Enhanced Modularity**: The schema now explicitly supports splitting large
+    configuration files into smaller, more manageable parts. By utilizing
+    inclusion mechanisms, you can maintain different sections of the portal
+    (like ``<categories>`` or specific products) in separate files, leading to
+    a cleaner and more maintainable structure.
+
+  * **Implicit Language Logic**: Master/source language identification
+    has shifted from a boolean attribute (``@default``) to a value-based system.
+    The schema now assumes ``en-us`` is the source locale for products and deliverables.
+
+  * **Migration Tooling**: To facilitate the transition, an XSLT migration
+    stylesheet is available. This tool automates the conversion of version
+    6.0 configuration files to the 7.0 format, handling the renaming of
+    elements, restructuring of attributes, and the removal of deprecated metadata. (:gh:`187`)
+
+
 Version 0.17.0
 ==============
 

changelog.d/+depupdates.infra.rst

@@ -10,9 +10,18 @@ To build the documentation for this project, use the following steps:
 #. Build the HTML documentation using the :ref:`makedocs <devel-helpers>` command:
 
    .. code-block:: shell-session
-      :caption: Building the documentation
       :name: makedocs
 
       makedocs
 
-#. Find the generated documentation in the :file:`docs/build/html` directory.
+   If you want to have a bit more control, use this command:
+
+   .. code-block:: shell-session
+      :name: sphinx-build
+
+      uv run --frozen make -C docs html
+
+#. Watch for warnings and errors during the build process.
+   If you encounter any issues, review the output and fix them accordingly.
+
+Find the generated documentation in the :file:`docs/build/html` directory.

changelog.d/112.bugfix.rst

@@ -3,22 +3,40 @@
 Creating a New Release
 ======================
 
-When you are ready to release a new version of the project, start with creating a new release branch. There you bump the version, build the changelog, and adjust minor things like the documentation. Avoid commiting changes that introduces new features or add breaking changes.
+A release is a snapshot of the project at a specific point in time, typically
+associated with a version number. It represents a stable and tested state of
+the project that can be shared with users. Creating a release involves several
+steps to ensure that the project is properly packaged, documented, and ready
+for distribution.
+
+Ensure the the following pre-requisites are met before starting the release process:
+
+* You have pulled the latest changes from the main branch of the repository.
+* You have the necessary permissions to create a release.
 
 Follow these steps:
 
-#. Ensure that you have the latest changes from the main branch of the repository.
 #. Create a new branch named ``release/<VERSION>``, where ``<VERSION>`` is the version number you are releasing (e.g., ``release/1.0.0``).
 #. :ref:`Bump the version <bump-version>`.
 #. :ref:`Update the project <update-project>`.
 #. :ref:`Build the changelog <build-changelog>`.
+#. :ref:`Build the documentation <build-docs>`.
+#. Optionally, look for Ruff issues:
+
+   .. code-block:: console
+
+      ruff check .
+
 #. In your current branch, push the branch to the remote repository:
 
    .. code-block:: console
 
       git push -u origin HEAD
 
-#. Wait for the CI to pass. If it fails, fix the issues and commit again.
-#. If the CI passes, (squash-)merge your release branch into the main branch.
-   The GitHub Action workflow will automatically create a new release based on the name of the release branch.
-#. Find the release in the GitHub repository under the |gh_release| section.
+#. Wait for the CI to pass.
+
+   * If it fails, fix the issues and commit again.
+   * If the CI passes, (squash-)merge your release branch into the main branch.
+     The GitHub Action workflow will automatically create a new release based on the name of the release branch.
+
+Find the new release in the GitHub repository under the |gh_release| section.