From 1c9809c73f7cfff8ea05369bc63fd52fd8501843 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Petr=20P=C3=ADsa=C5=99?= <ppisar@redhat.com>
Date: Wed, 1 Feb 2023 17:00:05 +0100
Subject: [PATCH] doc: Support for compressed documents is scheduled for
 removal

YUM repositories gain support for more and more compression formats.
That naturally means enhancing createrepo_c (a repository producer),
and librepo (a repository consumer). The repository works here as
a transport mechanism.

Therefore it does not make sense to duplicate the compression support
in libmodulemd. Especially if the main application is package manager
which uses librepo for retrieving YAML documents. These applications
can use librepo for decompressing the documents before passing them
into libmodulemd.

Compression support in libmodulemd needs magic (file) and rpm
libraries. Especially libmagic carry dozen-megabyte large file format
database. It is desired to remove compression support from
libmodulemd.

As a result, this patch marks compression support deprecated.

<https://github.com/fedora-modularity/libmodulemd/issues/606>
---
 modulemd/include/modulemd-2.0/modulemd-compression.h  | 11 +++++++++--
 modulemd/include/modulemd-2.0/modulemd-module-index.h |  3 +++
 modulemd/include/modulemd-2.0/modulemd.h              |  3 +++
 modulemd/modulemd-validator.1                         |  2 ++
 4 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/modulemd/include/modulemd-2.0/modulemd-compression.h b/modulemd/include/modulemd-2.0/modulemd-compression.h
index 758347688..ddb38b0b1 100644
--- a/modulemd/include/modulemd-2.0/modulemd-compression.h
+++ b/modulemd/include/modulemd-2.0/modulemd-compression.h
@@ -14,14 +14,19 @@
 #pragma once
 
 #include <glib.h>
+#include "modulemd-deprecated.h"
 
 G_BEGIN_DECLS
 
 /**
  * SECTION: modulemd-compression
  * @title: Modulemd Compression Helpers
- * @stability: stable
+ * @stability: unstable
  * @short_description: Utility functions for working with compressed files.
+ *
+ * Direct support for handling compressed YAML documents is scheduled for removal.
+ * If you work with compressed documents, first uncompress them and then pass
+ * the raw YAML documents to this library.
  */
 
 
@@ -37,6 +42,7 @@ G_BEGIN_DECLS
  * @MODULEMD_COMPRESSION_TYPE_SENTINEL: Enum list terminator
  *
  * Since: 2.8
+ * Deprecated: 2.14.1: Support for compressed documents is scheduled for removal.
  */
 typedef enum
 {
@@ -62,8 +68,9 @@ typedef enum
  * a known type.
  *
  * Since: 2.8
+ * Deprecated: 2.14.1: Support for compressed documents is scheduled for removal.
  */
-ModulemdCompressionTypeEnum
+MMD_DEPRECATED ModulemdCompressionTypeEnum
 modulemd_compression_type (const gchar *name);
 
 
diff --git a/modulemd/include/modulemd-2.0/modulemd-module-index.h b/modulemd/include/modulemd-2.0/modulemd-module-index.h
index e0757693e..2fef8cc57 100644
--- a/modulemd/include/modulemd-2.0/modulemd-module-index.h
+++ b/modulemd/include/modulemd-2.0/modulemd-module-index.h
@@ -163,6 +163,9 @@ modulemd_module_index_new (void);
  * @failures appropriately if any of the YAML subdocuments were invalid or
  * sets @error if there was a fatal parse error.
  *
+ * Support for compressed YAML files is deprecated. In the future this
+ * function will only support uncompressed YAML files.
+ *
  * Since: 2.0
  */
 gboolean
diff --git a/modulemd/include/modulemd-2.0/modulemd.h b/modulemd/include/modulemd-2.0/modulemd.h
index a9208e5e4..105a7cb7d 100644
--- a/modulemd/include/modulemd-2.0/modulemd.h
+++ b/modulemd/include/modulemd-2.0/modulemd.h
@@ -317,6 +317,9 @@ modulemd_get_version (void);
  * initialized with the content from @yaml_file. Returns NULL and sets @error
  * if the file is not completely valid.
  *
+ * Support for compressed YAML files is deprecated. In the future this
+ * function will only support uncompressed YAML files.
+ *
  * Since: 2.10
  */
 ModulemdModuleIndex *
diff --git a/modulemd/modulemd-validator.1 b/modulemd/modulemd-validator.1
index 8362b0640..e995d72e8 100644
--- a/modulemd/modulemd-validator.1
+++ b/modulemd/modulemd-validator.1
@@ -76,6 +76,8 @@ Print a usage text and then exit.
 .TP
 \fB\-V\fP, \fB\-\-version\fP
 Print a version number and then exit.
+.SH DEPRECATION NOTICE
+Support for compressed \fIFILES\fP is deprecated.
 .SH EXIT CODE
 If the supplied documents are valid (and satisfy the \fB--type\fP constrain),
 zero exit code will be returned.  Otherwise a non-zero code will be emitted.