Create developer documentation for disclosures.json

[carike]

Background:

The Disclosures Tab is an initiative that is underway in the Core Privacy Team.
The aim is to help site owners / admins better understand what information their site (plugins, themes and Core) collects, where the information is stored and where it is sent - and in particular, who it is shared with.
We hope to help site owners / admins make more informed privacy choices (e.g. when choosing which plugin to install) and to better understand their risk profile when it comes to privacy.
For the most part, the actual "controlling" is planned for a sibling plugin, the Permissions Tab, which is not currently intended to be merged into Core, as this will contain more advanced settings.
You can read more about the various privacy initiatives here: ​https://make.wordpress.org/core/2020/08/19/minutes-core-privacy-meeting-19-august-2020/

The Challenge:

To make #51092 understandable for plugin, theme and core developers, by providing a template and illustrative examples.

Scope:

The following tickets represent milestones for the Disclosures Tab:

#51092 proposes the schema.
[] will be created for the validation of the schema by Core.
[] will be created for internationalization.
This ticket only deals with developer documentation.
#51144 proposes a UI for site-level privacy disclosures and related settings.

The Solution:

Illustrative example: Licensing

In this example, a theme author would like to disclose the licenses that apply to the theme and its assets.
The author would include the following in a file named disclosures.json in the theme's main folder to indicate that:

• Their theme itself is licensed under the General Public License version 2;
• They make use of images, which are locally included in the theme, all of which they found on the "My Stock Photos" site;
• They make use of the Google Fonts CDN to serve the Andika, Cousine fonts and Ubuntu fonts.

<?php
{
   "licenses": {
      "code": [
         "https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html"
      ],
      "localAssets": [
         "https://creativecommons.org/publicdomain/zero/1.0/legalcode"
      ],
      "remoteAssets": [
         "https://scripts.sil.org/cms/scripts/page.php?item_id=OFL_web",
         "http://www.apache.org/licenses/LICENSE-2.0.html", 
         "https://ubuntu.com/legal/font-licence"
      ]
   }
}

Illustrative example: Calls to External Networks

In this example, a plugin author would like to disclose that their code makes calls to external networks.
The author would like to include the following in a file named disclosures.json in the plugin's main folder to indicate that:

• The code includes an external reference to the developer's own site (if the user opts in to send tracking data) in the PHP;
• The code includes an external reference to Google Analytics in the JavaScript;
• The code includes an external reference to Google Fonts in the CSS.

<?php
{
   "policies": {
      "PHP": [
         "https://developersite.example.com/privacy-policy/"
      ],
      "JavaScript": [
         "https://policies.google.com/privacy"
      ],
      "CSS": [
         "https://policies.google.com/privacy"
      ]
   }
}

Illustrative example: Database Management

In this example, a plugin author would like to disclose how their code interacts with the site's database(s).
The author would include the following in a file named disclosures.json in the plugin's main folder to indicate that:

• The plugin does not write information to the database that was not explicitly input by a(n authorized) user;
• The plugin does write information to the database that was explicitly input by a(n authorized) user;
• The plugin creates a Custom Post Type called ExampleCPT;
• The plugin allows a(n authorized) user to create their own Custom Post Types;
• The plugin creates a custom table called PluginTable;
• The plugin allows a(n authorized) user to create their own custom tables.

<?php
{
   "database": {
      "writesToDB": {
         "auto": [
            FALSE
         ],
         "manual": [
            TRUE,
            "edit_private_posts"
         ]
      },
      "CPT": {
         "auto": [
            TRUE,
            "ExampleCPT"
         ],
         "manual": [
            TRUE,
            "delete_private_posts"
         ]
      },
      "customTables": {
         "auto": [
            TRUE,
            "PluginTable"
         ],
         "manual": [
            TRUE,
            "delete_plugins"
         ]
      }
   }
}

Illustrative example: Compatibility

In this example, a plugin author would like to disclose which Privacy Tools they, in good faith, believe that they are compatible with.
The author would include the following in a file named disclosures.json in the plugin's main folder to indicate that:

• The code is compatible with Core's tool to export Protected Personal Information;
• The code is compatible with Core's tool to erase Protected Personal Information;
• The code is compatible with the Consent API;
• The code is compatible with the Disclosures Tab;
• The code is not compatible with the Permissions Tab.

<?php
{
   "compatibility": {
      "ppiExport": [
         TRUE
      ],
      "ppiErasure": [
         TRUE
      ],
      "consentAPI": [
         TRUE
      ],
      "disclosuresTab": [
         TRUE
      ],
      "permissionsTab": [
         FALSE
      ]
   }
}

Illustrative example: Monetization

In this example, a theme author would like to disclose their monetization practices.
The theme author would include the following in a file named disclosures.json in the theme's main folder to indicate that:

• The code contains or generates promotion for other products or services from the same author(s);
• The code does not contain or generate requests for, or a mechanism to donate to the author(s);
• The code contains or requests a backlink, in the form of a footer credit;
• The code does not contain or generate affiliate links;
• The code does not contain or generate paid promotion for products or services from others who are not the author(s).

<?php
{
   "monetization": {
      "upsells": [
         TRUE, 
         "https://example.com/ToS/devsite/"
      ],
      "donations": [
         FALSE
      ],
      "backlinks": [
         TRUE, 
         "https://example.com/ToS/devsite/"
      ],
      "affiliates": [
         FALSE
      ],
      "advertising": [
         FALSE
      ]
   }
}

[azaozz]

Sorry but seems I'm missing something. This is a trac ticket to add developer documentation ...where? In WP core or on the wordpress.org website?

If the former: where in core should such developer documentation be? How should it be displayed (UI, design, etc.)? Why should it be in core and not together with the rest of the developer docs?

If the latter, trac is not the appropriate place. Please have a look at ​https://codex.wordpress.org/Developer_Documentation.

[carike]

:wave: @azaozz

#51092 deals with the JSON schema needed by Core (disclosures-schema.json).
This ticket deals with the template / format plugin developers need to use in their individual plugin / theme (disclosures.json).

Basically, this ticket is meant for the people who want the digest version of what they need to do in their plugin / theme and do not want to actively participate in determining what Core does with that information and how.
Making it less abstract by designing the documentation at the same time as the template (well, at this point a little before, I still need to amend the ticket description to add the actual template), helps stakeholder management by helping to improve communication and encourage participation.
It also saves some time and helps ensure that documentation is not an after-thought. It is particularly important for this initiative, since we will need to undertake education drives for developers.
Since the aim of the initiative is to standardize the way that privacy and related disclosures are made, it is only useful if it is widely adopted by developers. Buy in from developers (and those managing the repositories) are thus crucial to success.

While the disclosures.json template does apply to Core (since it is the "input" for disclosures-schema.json), the documentation part will be re-homed as soon as we've built consensus on what they should look like.

[azaozz]

Replying to carike:

This ticket deals with the template / format plugin developers need to use in their individual plugin / theme (disclosures.json).

Basically, this ticket is meant for the people who want the digest version of what they need to do in their plugin / theme and do not want to actively participate in determining what Core does with that information and how.

Right, exactly :)

Trac is for making changes and additions to WP core, usually code but also inline docs (for functions), unit tests, etc.

Developer documentation "lives" on the wp.org website. In this case the proper place is ​https://developer.wordpress.org/plugins/. Adding content and making changes there is the "job" of the WP Docs team.

I agree in this case the docs are quite harder to write and get right, and input from multiple people/sources is needed. To facilitate collaboration it seems best to use Github (as it allows inline comments, multiple changes, etc.), then (perhaps) link the PR to this ticket.

Then, after the docs are deemed ready, the Docs team can review them and include them in the WP ​Plugin Developer Handbook.

[garrett-eclipse]

5.6 beta is coming up quickly, will revisit in a future release.

[garrett-eclipse]

Dropping privacy focus as it's already in the Privacy component.