From 8612074d1401a59e394e1361eefadebd2d82ae04 Mon Sep 17 00:00:00 2001
From: ArthurW <arthur@tarides.com>
Date: Mon, 6 Jan 2025 13:43:03 +0100
Subject: [PATCH] Document maintenance_intent

---
 doc/howto/opam-file-generation.rst                 |  2 ++
 doc/reference/dune-project/generate_opam_files.rst | 12 ++++++++++++
 doc/reference/dune-project/package.rst             |  6 ++++++
 3 files changed, 20 insertions(+)

diff --git a/doc/howto/opam-file-generation.rst b/doc/howto/opam-file-generation.rst
index 9fbe584cf7e..319a66ab957 100644
--- a/doc/howto/opam-file-generation.rst
+++ b/doc/howto/opam-file-generation.rst
@@ -81,6 +81,7 @@ For example, if your opam file looks like:
      "conduit-async" { >= "1.0.3" }
      "async" { >= "v0.10.0" }
    ]
+   x-maintenance-intent: [ "(latest)" ]
 
 You can express this as::
 
@@ -88,6 +89,7 @@ You can express this as::
    (license ISC)
    (authors "Anil Madhavapeddy" "Rudi Grinberg")
    (maintainers "team@mirage.org")
+   (maintenance_intent "(latest)")
 
    (package
     (name cohttp-async)
diff --git a/doc/reference/dune-project/generate_opam_files.rst b/doc/reference/dune-project/generate_opam_files.rst
index cf0c8e128c3..4e441cab9cf 100644
--- a/doc/reference/dune-project/generate_opam_files.rst
+++ b/doc/reference/dune-project/generate_opam_files.rst
@@ -63,6 +63,18 @@ defined in the project:
        "Jane Doe <jane.doe@example.com>"
        "John Doe <john.doe@example.com>")
 
+.. describe:: (maintenance_intent <strings>)
+
+   .. versionadded:: 3.18
+
+   Specify the `opam maintenance intent <https://github.com/ocaml/opam-repository/blob/master/governance/policies/archiving.md#specification-of-the-x--fields-used-in-the-archiving-process>`.
+
+   Example:
+
+   .. code:: dune
+
+      (maintenance_intent "(latest)")
+
 .. describe:: (source ...)
 
    .. versionadded:: 1.7
diff --git a/doc/reference/dune-project/package.rst b/doc/reference/dune-project/package.rst
index f90580ff31a..19f7ed017c2 100644
--- a/doc/reference/dune-project/package.rst
+++ b/doc/reference/dune-project/package.rst
@@ -60,6 +60,12 @@ package
 
       The same as (and takes precedences over) the corresponding global field.
 
+   .. describe:: (maintenance_intent ...)
+
+      .. versionadded:: 3.18
+
+      The same as (and takes precedences over) the corresponding global field.
+
    .. describe:: (source ...)
 
       .. versionadded:: 2.0