doc: move policy docs to the permissions scope

[RafaelGSS]

During the journey of the Permission System, we've felt the necessity to expand the policy documentation to include the permissions (#44004). The principal idea is to avoid confusion between policy and permissions.

Note: I've included the Process-based permission just to simulate how it gonna work along with the Permission System. Once it's approved, I'll remove and keep just the Resource-based permission.

Reference: nodejs/security-wg#791 (comment)

[RafaelGSS]

I'm not quite sure if Resource-based permission would improve the UX. Even accepting resources such as data:, I see Module-based permissions better even being not 100% accurate. Happy to see your thoughts.

[GeoffreyBooth]

Sure, “Module-based permissions” sounds fine to me. Maybe ask at the next Security WG meeting which sounds better to most people and go with that.

[RafaelGSS]

Would renaming the file still keep the current link (https://nodejs.org/api/policy.html) active? at least for HTTP 301

cc: @nodejs/documentation

[RafaelGSS]

ping: @nodejs/security-wg

[richardlau]

Would renaming the file still keep the current link (https://nodejs.org/api/policy.html) active? at least for HTTP 301

cc: @nodejs/documentation

It would not -- once a release containing the renamed file is released that link would become a dead one.

[GeoffreyBooth]

Sure, “Module-based permissions” sounds fine to me. Maybe ask at the next Security WG meeting which sounds better to most people and go with that.

[GeoffreyBooth]

Would renaming the file still keep the current link (nodejs.org/api/policy.html) active? at least for HTTP 301
cc: @nodejs/documentation

It would not – once a release containing the renamed file is released that link would become a dead one.

We should figure out how to ensure the redirect before we land the rename. Could we keep a policy.md file that’s a one-liner like “Please see Permissions” with a link, and that way policy.html stays active? And we somehow keep “Policy” out of the sidebar and table of contents. It wouldn’t be a 301 redirect but I’m not sure that an automated redirect is really necessary; there’s something to be said for the manual redirect educating users that the old feature has been renamed and incorporated into something larger.

[RafaelGSS]

We should figure out how to ensure the redirect before we land the rename. Could we keep a policy.md file that’s a one-liner like “Please see Permissions” with a link, and that way policy.html stays active?

Yes, we've agreed on that approach in the last security WG too.

[RafaelGSS]

@GeoffreyBooth Instead removing all the content of policy.md, I've added a new line telling the users to refer to the another document. I belive this way won't break referrals link (like https://nodejs.org/api/policy.html#error-behavior) nor reduce the searchable content on google. What do you think?

We just need to make the statement stronger and show it better somehow. Also, I can totally remove the content and keep a single line, but I'm afraid about the impact.

[GeoffreyBooth]

Instead removing all the content of policy.md

We shouldn't have two copies of the same content, it'll fall out of date. Hashtag (anchor) links will still work even if the headings are removed.

[RafaelGSS]

Instead removing all the content of policy.md

We shouldn't have two copies of the same content, it'll fall out of date. Hashtag (anchor) links will still work even if the headings are removed.

Removed

[GeoffreyBooth]

I don’t think we should list it in the sidebar. It was only ever an experimental API, and not a hugely popular one. People will figure it out.

Suggested change

* [Policy](policy.md) - Deprecated

[RafaelGSS]

Our tests require it. I'll need to bypass it somehow.

[GeoffreyBooth]

@Trott @nodejs/documentation thoughts?

[RafaelGSS]

Well... I bypass it on: bc61b8c

[RafaelGSS]

@GeoffreyBooth it should be ready now. Thanks for the review

[RafaelGSS]

Since it's a namespace change, I prefer to have at least two @nodejs/tsc approvals. Could someone else review it, please?

[mcollina]

lgtm

[nodejs-github-bot]

Commit Queue failed

- Loading data for nodejs/node/pull/44222
✔  Done loading data for nodejs/node/pull/44222
----------------------------------- PR info ------------------------------------
Title      doc: move policy docs to the permissions scope (#44222)
Author     Rafael Gonzaga  (@RafaelGSS)
Branch     RafaelGSS:doc/rename-policy-documentation -> nodejs:main
Labels     doc
Commits    3
 - doc: move policy docs to the permissions scope
 - doc: rename policy references
 - test: bypass renamed fields holding the old link
Committers 1
 - RafaelGSS 
PR-URL: https://github.com/nodejs/node/pull/44222
Reviewed-By: Geoffrey Booth 
Reviewed-By: Matteo Collina 
------------------------------ Generated metadata ------------------------------
PR-URL: https://github.com/nodejs/node/pull/44222
Reviewed-By: Geoffrey Booth 
Reviewed-By: Matteo Collina 
--------------------------------------------------------------------------------
   ℹ  This PR was created on Fri, 12 Aug 2022 16:18:12 GMT
   ✔  Approvals: 2
   ✔  - Geoffrey Booth (@GeoffreyBooth) (TSC): https://github.com/nodejs/node/pull/44222#pullrequestreview-1094107097
   ✔  - Matteo Collina (@mcollina) (TSC): https://github.com/nodejs/node/pull/44222#pullrequestreview-1095708158
   ✔  Last GitHub CI successful
   ℹ  Last Full PR CI on 2022-09-02T13:14:14Z: https://ci.nodejs.org/job/node-test-pull-request/46388/
- Querying data for job/node-test-pull-request/46388/
   ✔  Last Jenkins CI successful
--------------------------------------------------------------------------------
   ✔  No git cherry-pick in progress
   ✔  No git am in progress
   ✔  No git rebase in progress
--------------------------------------------------------------------------------
- Bringing origin/main up to date...
From https://github.com/nodejs/node
 * branch                  main       -> FETCH_HEAD
✔  origin/main is now up-to-date
- Downloading patch for 44222
From https://github.com/nodejs/node
 * branch                  refs/pull/44222/merge -> FETCH_HEAD
✔  Fetched commits as 4af0a264da73..3e6c93b1765e
--------------------------------------------------------------------------------
[main 9b98e158b8] doc: move policy docs to the permissions scope
 Author: RafaelGSS 
 Date: Fri Aug 12 13:09:32 2022 -0300
 1 file changed, 33 insertions(+), 6 deletions(-)
 rename doc/api/{policy.md => permissions.md} (92%)
Auto-merging doc/api/errors.md
[main e126e7227f] doc: rename policy references
 Author: RafaelGSS 
 Date: Fri Aug 12 13:30:08 2022 -0300
 4 files changed, 25 insertions(+), 23 deletions(-)
 create mode 100644 doc/api/policy.md
[main 4ab2177e1d] test: bypass renamed fields holding the old link
 Author: RafaelGSS 
 Date: Wed Aug 31 10:41:53 2022 -0300
 2 files changed, 18 insertions(+), 12 deletions(-)
   ✔  Patches applied
There are 3 commits in the PR. Attempting autorebase.
Rebasing (2/6)
Executing: git node land --amend --yes

--------------------------------- New Message ----------------------------------

doc: move policy docs to the permissions scope
PR-URL: #44222

Reviewed-By: Geoffrey Booth webadmin@geoffreybooth.com

Reviewed-By: Matteo Collina matteo.collina@gmail.com
[detached HEAD 08d841c195] doc: move policy docs to the permissions scope

Author: RafaelGSS rafael.nunu@hotmail.com

Date: Fri Aug 12 13:09:32 2022 -0300

1 file changed, 33 insertions(+), 6 deletions(-)

rename doc/api/{policy.md => permissions.md} (92%)

Rebasing (3/6)

Rebasing (4/6)
Executing: git node land --amend --yes

--------------------------------- New Message ----------------------------------

doc: rename policy references
PR-URL: #44222

Reviewed-By: Geoffrey Booth webadmin@geoffreybooth.com

Reviewed-By: Matteo Collina matteo.collina@gmail.com
[detached HEAD a03e6fb7e4] doc: rename policy references

Author: RafaelGSS rafael.nunu@hotmail.com

Date: Fri Aug 12 13:30:08 2022 -0300

4 files changed, 25 insertions(+), 23 deletions(-)

create mode 100644 doc/api/policy.md

Rebasing (5/6)

Rebasing (6/6)
Executing: git node land --amend --yes

--------------------------------- New Message ----------------------------------

test: bypass renamed fields holding the old link
PR-URL: #44222

Reviewed-By: Geoffrey Booth webadmin@geoffreybooth.com

Reviewed-By: Matteo Collina matteo.collina@gmail.com
[detached HEAD 7733587048] test: bypass renamed fields holding the old link

Author: RafaelGSS rafael.nunu@hotmail.com

Date: Wed Aug 31 10:41:53 2022 -0300

2 files changed, 18 insertions(+), 12 deletions(-)
Successfully rebased and updated refs/heads/main.
ℹ  Add commit-queue-squash label to land the PR as one commit, or commit-queue-rebase to land as separate commits.

https://github.com/nodejs/node/actions/runs/2994613295

[nodejs-github-bot]

Landed in 03553c5

[UlisesGascon]

LGTM!