From 0fff11c4e9eff2f236d46360cf4177c7d1f406b1 Mon Sep 17 00:00:00 2001
From: RafaelGSS <rafael.nunu@hotmail.com>
Date: Fri, 12 Aug 2022 13:30:08 -0300
Subject: [PATCH] doc: rename policy references

---
 doc/api/errors.md      |  2 +-
 doc/api/index.md       |  3 ++-
 doc/api/permissions.md | 44 ++++++++++++++++++++++--------------------
 doc/api/policy.md      | 11 +++++++++++
 4 files changed, 37 insertions(+), 23 deletions(-)
 create mode 100644 doc/api/policy.md

diff --git a/doc/api/errors.md b/doc/api/errors.md
index 4c544ef734776e..0608cacce13ec0 100644
--- a/doc/api/errors.md
+++ b/doc/api/errors.md
@@ -3577,7 +3577,7 @@ The native call from `process.cpuUsage` could not be processed.
 [domains]: domain.md
 [event emitter-based]: events.md#class-eventemitter
 [file descriptors]: https://en.wikipedia.org/wiki/File_descriptor
-[policy]: policy.md
+[policy]: permissions.md#policies
 [self-reference a package using its name]: packages.md#self-referencing-a-package-using-its-name
 [stream-based]: stream.md
 [syscall]: https://man7.org/linux/man-pages/man2/syscalls.2.html
diff --git a/doc/api/index.md b/doc/api/index.md
index c999258769c95b..da91b2a07cd1ec 100644
--- a/doc/api/index.md
+++ b/doc/api/index.md
@@ -45,7 +45,8 @@
 * [OS](os.md)
 * [Path](path.md)
 * [Performance hooks](perf_hooks.md)
-* [Policies](policy.md)
+* [Permissions](permissions.md)
+* [Policy](policy.md) - Deprecated
 * [Process](process.md)
 * [Punycode](punycode.md)
 * [Query strings](querystring.md)
diff --git a/doc/api/permissions.md b/doc/api/permissions.md
index fe6385c7e1dd70..af9f39e7991908 100644
--- a/doc/api/permissions.md
+++ b/doc/api/permissions.md
@@ -1,26 +1,30 @@
 # Permissions
 
-This section exposes security features available to be adopted in a
-Node.js application. The available scopes are:
+Permissions can be used to control what system resources the
+Node.js process has access to or what actions the process can take
+with those resources. Permissions can also control what modules can
+be accessed by other modules.
+
+* [Process-based permissions](#process-based-permissions) control the Node.js
+  process's access to resources such as the file system or the network.
+  The resource can be entirely allowed or denied, or actions related to it can
+  be controlled; for example, you can allow file system reads while denying
+  writes.
+
+* [Module-based permissions](#module-based-permissions) control which files
+  or URLs are available to other modules during application execution.
+  This can be used to control what modules can be accessed by third-party
+  dependencies, for example.
+
+Both types of permissions can be used together to provide a
+safer environment. If you find a potential security vulnerability,
+please refer to our [Security Policy][].
 
-* [Resource-based permissions](#resource-based-permissions)
-* [Process-based permissions](#process-based-permissions)
-
-Resource-based permissions stands for the managment of modules using
-policies. A policy can guarantee which module/resource is available
-during the application execution.
-
-Process-based permissions stands for the management of resources such
-as _File System_ or _Network_. A permission can be configured to restrict
-access to specific resources, for instance, one can restrict access to
-all the _File System_ write.
-
-Both permissions can be used together to provide a safer environment.
+## Process-based permissions
 
-**Note**: if you find a potential security vulnerability on Node.js,
-refer to our [Security Policy][].
+// STUB
 
-## Resource-based permissions
+## Module-based permissions
 
 ## Policies
 
@@ -447,9 +451,7 @@ not adopt the origin of the `blob:` URL.
 Additionally, import maps only work on `import` so it may be desirable to add a
 `"import"` condition to all dependency mappings.
 
-## Process-based permissions
-
+[Security Policy]: https://github.com/nodejs/node/blob/main/SECURITY.md
 [import maps]: https://url.spec.whatwg.org/#relative-url-with-fragment-string
 [relative-url string]: https://url.spec.whatwg.org/#relative-url-with-fragment-string
 [special schemes]: https://url.spec.whatwg.org/#special-scheme
-[Security Policy]: https://github.com/nodejs/node/blob/main/SECURITY.md
diff --git a/doc/api/policy.md b/doc/api/policy.md
new file mode 100644
index 00000000000000..5e812ae0c50abd
--- /dev/null
+++ b/doc/api/policy.md
@@ -0,0 +1,11 @@
+# Policies
+
+<!--introduced_in=v11.8.0-->
+
+<!-- type=misc -->
+
+> Stability: 1 - Experimental
+
+The former Policies API is now the \[Module-Based Permissions API]\[].
+
+[Module-Based Permissions]: permissions.md#module-based-permissions