From aed52f574cfd57eec77e699ace7dab84aff99a0a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Romain=20Tarti=C3=A8re?= <romain@blogreen.org>
Date: Thu, 5 Oct 2023 11:22:43 -1000
Subject: [PATCH] Improve nginx::package_source documentation

This is not a free-form String so prefer an enum and add some
documentation about the supported values.
---
 REFERENCE.md            | 20 +++++++++++++++++++-
 manifests/init.pp       |  2 +-
 types/package_source.pp | 18 ++++++++++++++++++
 3 files changed, 38 insertions(+), 2 deletions(-)
 create mode 100644 types/package_source.pp

diff --git a/REFERENCE.md b/REFERENCE.md
index ee9405b72..9d796abe3 100644
--- a/REFERENCE.md
+++ b/REFERENCE.md
@@ -37,6 +37,7 @@
 * [`Nginx::ErrorLogSeverity`](#Nginx--ErrorLogSeverity)
 * [`Nginx::GzipProxied`](#Nginx--GzipProxied): custom type for gzip_proxied
 * [`Nginx::LogFormat`](#Nginx--LogFormat)
+* [`Nginx::Package_source`](#Nginx--Package_source): Where to download NGINX from  There are three versions of NGINX available: * stable (`nginx` or `nginx-stable`); * mainline (`nginx-mainline`
 * [`Nginx::Size`](#Nginx--Size)
 * [`Nginx::StringMappings`](#Nginx--StringMappings): custom type for the `map` variable mapping
 * [`Nginx::Time`](#Nginx--Time)
@@ -1449,7 +1450,7 @@ Default value: `$nginx::params::package_name`
 
 ##### <a name="-nginx--package_source"></a>`package_source`
 
-Data type: `String`
+Data type: `Nginx::Package_source`
 
 
 
@@ -5186,6 +5187,23 @@ Variant[String[1], Struct[{
   }]]
 ```
 
+### <a name="Nginx--Package_source"></a>`Nginx::Package_source`
+
+Where to download NGINX from
+
+There are three versions of NGINX available:
+* stable (`nginx` or `nginx-stable`);
+* mainline (`nginx-mainline`);
+* passenger (`passenger`).
+
+The mainline branch gets new features and bugfixes sooner but might introduce new bugs as well. Critical bugfixes are backported to the stable branch.
+
+In general, the stable release is recommended, but the mainline release is typically quite stable as well.
+
+In addition, Phusion provide packages for NGINX + Passenger (`passenger`).
+
+Alias of `Enum['nginx', 'nginx-stable', 'nginx-mainline', 'passenger']`
+
 ### <a name="Nginx--Size"></a>`Nginx::Size`
 
 The Nginx::Size data type.
diff --git a/manifests/init.pp b/manifests/init.pp
index f78afd2e5..e63cf5ce9 100644
--- a/manifests/init.pp
+++ b/manifests/init.pp
@@ -200,7 +200,7 @@
   ### START Package Configuration ###
   String $package_ensure                                     = installed,
   String $package_name                                       = $nginx::params::package_name,
-  String $package_source                                     = 'nginx',
+  Nginx::Package_source $package_source                      = 'nginx',
   Optional[String] $package_flavor                           = undef,
   Boolean $manage_repo                                       = $nginx::params::manage_repo,
   Hash[String[1], String[1]] $mime_types                     = $nginx::params::mime_types,
diff --git a/types/package_source.pp b/types/package_source.pp
new file mode 100644
index 000000000..1e7c2ba7c
--- /dev/null
+++ b/types/package_source.pp
@@ -0,0 +1,18 @@
+# Where to download NGINX from
+#
+# There are three versions of NGINX available:
+# * stable (`nginx` or `nginx-stable`);
+# * mainline (`nginx-mainline`);
+# * passenger (`passenger`).
+#
+# The mainline branch gets new features and bugfixes sooner but might introduce new bugs as well. Critical bugfixes are backported to the stable branch.
+#
+# In general, the stable release is recommended, but the mainline release is typically quite stable as well.
+#
+# In addition, Phusion provide packages for NGINX + Passenger (`passenger`).
+type Nginx::Package_source = Enum[
+  'nginx',
+  'nginx-stable',
+  'nginx-mainline',
+  'passenger',
+]