Contribute

We're thrilled that you want to contribute to PrivacySpy. This guide will explain how to contribute policies, corrections, suggestions, and code changes.

Note that all contributions to PrivacySpy will take place in our GitHub repository. If you don't have a GitHub account already, you'll need to sign up for one to participate.

To see all of PrivacySpy's existing contributors, check out our contributors page.

Table of Contents

• Sharing suggestions and requests
• Submitting a new product
• Changing an existing product
• Product assessment guide
• Contributors file guide

Sharing suggestions and requests

If you have an idea for PrivacySpy, think you found an error, or just want to bring something up with the team, feel free to create an issue in our GitHub repository. Creating issues in the GitHub repository is the best way to share feedback and comments.

If your issue is a suggestion—such as a request to add a new product to our database or to fix an error—consider making the change yourself and submitting your modifications as a pull request (see changing an existing policy below to learn how). If you're not comfortable implementing the change yourself or don't know how, though, feel free to just create an issue.

Submitting a new product

Submitting a new product to PrivacySpy isn't too hard. The first step is to fork PrivacySpy so that you can submit changes as a pull request—if you're unsure what this means, you can learn about pull requests here.

Once you have a version of PrivacySpy on your own GitHub account, here are the general steps you need to take to add a new product:

1. Create a new file in the products/ directory called <product slug>.toml. (A slug is a short and unique ID.) For example, if you were adding DuckDuckGo, the name of the file would be duckduckgo.toml. TOML is the file format we use for writing policies; if you're unfamiliar with it, you can learn more about TOML here.

2. Add an icon for your new product to the icons/ directory. The name of the icon file should correspond to the product slug from Step 1; for example, for DuckDuckGo, you'd want to name the icon file duckduckgo.png or duckduckgo.jpg. Icon images should be square and smaller than 30kb. You may use our script that helps you add icons quickly; to use it, simply run npm run icons and manually check if the icon has been downloaded and is correct.

3. Add yourself to CONTRIBUTORS.toml if you haven't already. Fill out as much or as little information as you want. For information about how this file works, refer to the contributors file guide below.

4. Fill in all the necessary info in the <product slug>.toml file. Refer to the product assessment guide below to learn about how this file works.

5. Make sure all tests pass. You can run tests using the npm test command. To ensure high-quality content, PrivacySpy has an automated system to check whether changes are appropriate. While it won't catch all issues, the automated testing system will let you know if you've made any obvious mistakes.

6. Once all tests pass, submit a pull request! To add your changes back to PrivacySpy, submit a pull request. (Be sure to follow the instructions in the Pull Request message template.) Once you do, a member of the PrivacySpy team will look over your changes and either merge or request revisions. Don't worry if your changes aren't accepted on the first try—mistakes are inevitable. Just implement the requested changes, then resubmit the pull request!

7. That's it! Congratulations—you've contributed a policy to PrivacySpy!

Changing an existing product

To change an existing product on PrivacySpy—to submit a correction or an update—you'll need to submit a pull request. Fortunately, this process is quite simple: just edit the product file in the products/ directory! To edit Google's entry, for example, simply edit the file at products/google.toml. Then, run the npm test command and make sure all tests pass. Finally, submit your changes as a pull request. (Be sure to follow the instructions in the Pull Request message template.)

To learn about how the product TOML file works, review the product assessment guide below.

Product assessment guide

Each product on PrivacySpy is stored in the products/ directory as a TOML file. If you're unfamiliar with the TOML file format, you can learn about it here. In short, it's a flexible data serialization format like JSON or YAML that's designed to be written and understood by humans. You can check if your TOML file is valid using this online tool.

If you're ever confused about the file format for products, you can always look at another existing product file for reference (such as this one).

Product metadata

Metadata about the product—the name, description, and hostnames, for example—belongs at the top of the product file. For metadata, we use a simple key = "value" format.

• name: this field holds the product's human-readable name as a string. Spaces and capitalization are allowed. For example, for DuckDuckGo, the value of name would be DuckDuckGo.

• description: this field contains the description of the product as a string. The description should be a complete sentence, and often mentions the owner and/or country of the product.

• slug: this field contains the product's slug (its unique ID). The slug can contain only letters, numbers, and dashes. No two products can have the same slug, because the slug determines the URL where the policy will be hosted. (For example, a product with the slug duckduckgo would be accessible at /product/duckduckgo.) The slug should be the same as the file but without .toml.

• hostnames: this field contains an array of strings; each string should be a hostname (i.e., domain name) of the product. For example, the value of hostnames for 1Password is ["1password.com"]. (Don't worry about subdomains; you don't need to include my.1password.com if you include 1password.com.) Usually, this array has only one element, but there are some cases when a product has multiple hostnames (e.g., GitHub, which uses ["github.com", "github.io"]).

• sources: this field contains an array of strings; each string should be the URL of a source used in grading the policy. (Almost always, the company's privacy policy itself would be included here as a source. Sometimes you'd want to include the company's security policy as well, if they have one.)

• contributors: this field contains an array of strings; each string corresponds to the slug of each contributor (you!) in the CONTRIBUTORS.toml file. See the contributors file guide below for more information. Usually, people use their GitHub username as their slug.

name = "Twitter"
description = "Twitter is a microblogging social network and is popular among American public figures."
slug = "twitter"
hostnames = [ "twitter.com" ]
sources = [ "https://twitter.com/en/privacy" ]
contributors = [ "milesmcc" ]

Product grading (rubric)

The next section of the product file is the rubric. This is where we encode the score of the product across each of the rubric questions.

Each question is included in the file with the following structure:

[rubric.<question ID>]
value = "<answer ID>"
citations = [
  # Direct quotes from the sources that support the value, if applicable. (Strings.)
]
notes = [
  # Any special notes you want to include about the selection. (Strings.)
]

Each question has an ID (<question id>, also known as the question's slug), and each possible value of that question also has an ID. For example, the question that assesses whether the product uses behavioral marketing has the id behavioral-marketing, and the IDs of the answers are yes, yes-opt-out (yes, but you can opt-out), yes-opt-in (yes, but you must opt-in), and no.

Note that all questions must be graded, and each grade must have at least one citation or note (as shown above).

Questions & options

[rubric.behavioral-marketing]
value = "yes" / "yes-opt-out" / "yes-opt-in" / "no" 
citations = ["Citations, if applicable"]
notes = ["Any notes, if applicable"]

[rubric.data-breaches]
value = "no" / "eventually" / "yes-72" / "na" 
citations = ["Citations, if applicable"]
notes = ["Any notes, if applicable"]

[rubric.data-collection-reasoning]
value = "no" / "somewhat" / "mostly" / "yes" / "na" 
citations = ["Citations, if applicable"]
notes = ["Any notes, if applicable"]

[rubric.data-deletion]
value = "no" / "yes-contact" / "yes-automated" / "na" 
citations = ["Citations, if applicable"]
notes = ["Any notes, if applicable"]

[rubric.history]
value = "no" / "last-modified" / "yes" 
citations = ["Citations, if applicable"]
notes = ["Any notes, if applicable"]

[rubric.law-enforcement]
value = "always" / "unspecified" / "reasonable" / "strict" / "na" / "never" 
citations = ["Citations, if applicable"]
notes = ["Any notes, if applicable"]

[rubric.list-collected]
value = "no" / "summarily" / "generally" / "exhaustively" / "na" 
citations = ["Citations, if applicable"]
notes = ["Any notes, if applicable"]

[rubric.noncritical-purposes]
value = "no" / "opt-out-some" / "opt-out-all" / "opt-in" / "na" 
citations = ["Citations, if applicable"]
notes = ["Any notes, if applicable"]

[rubric.revision-notify]
value = "no" / "yes" / "na" 
citations = ["Citations, if applicable"]
notes = ["Any notes, if applicable"]

[rubric.security]
value = "no" / "somewhat" / "yes" / "yes-audits" / "yes-independent-audits" / "na" 
citations = ["Citations, if applicable"]
notes = ["Any notes, if applicable"]

[rubric.third-party-access]
value = "yes-unspecified" / "yes-specified-noncritical" / "yes-unspecified-critical" / "yes-specified-critical" / "no" 
citations = ["Citations, if applicable"]
notes = ["Any notes, if applicable"]

[rubric.third-party-collection]
value = "yes" / "critical-only" / "no" 
citations = ["Citations, if applicable"]
notes = ["Any notes, if applicable"]

Updates

Whenever a product has a major privacy-related event (such as a data breach, an overhaul of their privacy policy, or anything else of this nature), we try to include it as an update on PrivacySpy.

Each product has an array of update objects. An update object (inside the updates array) looks like this:

[[updates]]
title = "Data Breach"
description = "More than 540 million records about Facebook users were publicly exposed on Amazon's cloud computing service, according to a cybersecurity research firm."
date = 2019-08-28
sources = [ "https://www.cbsnews.com/news/millions-facebook-user-records-exposed-amazon-cloud-server/" ]

As you can probably gather, title is a string that represents the title of the update; description is a string that explains what happened (in full sentences); date is the date of the update; and sources is an array of URLs that provide information about the update.

Note that to insert the update into the updates array, we put [[update]] on top of the object, as per the TOML spec.

Contributors file guide

Contributors like you deserve to be recognized for your additions to PrivacySpy. That's why we maintain the CONTRIBUTORS.toml file (in the root of the repository) where each contributor is listed with some minimal biographical information.

You aren't required to add any biographical information to the CONTRIBUTORS.toml file if you don't want to.

Here's a template for what to put in the file:

[your_slug] # usually the same as your GitHub username
name = "Your Name" # optional
website = "http://example.com" # optional
github = "example" # optional
email = "example@example.com" # optional

The only required element is [your_slug]. You can think of your_slug as your PrivacySpy "username"—it's what you'd add to the contributors array in policies you contribute to.