privacy.sexy/docs/collection-files.md

Collection files

• privacy.sexy is a data-driven application where it reads the necessary OS-specific logic from yaml files in application/collections
• 💡 Best practices
  • If you repeat yourself, try to utilize YAML-defined functions
  • Always try to add documentation and a way to revert a tweak in scripts
• 📖 Types in code: collection.yaml.d.ts

Objects

Collection

• A collection simply defines:
  • different categories and their scripts in a tree structure
  • OS specific details
• Also allows defining common functions to be used throughout the collection if you'd like different scripts to share same code.

Collection syntax

• os: string (required)
  • Operating system that the Collection is written for.
  • 📖 See OperatingSystem.ts enumeration for allowed values.
• actions: [ Category , ... ] (required)
  • Each category is rendered as different cards in card presentation.
  • ❗ A Collection must consist of at least one category.
• functions: [ Function , ... ]
  • Functions are optionally defined to re-use the same code throughout different scripts.
• scripting: ScriptingDefinition (required)
  • Defines the scripting language that the code of other action uses.

Category

• Category has a parent that has tree-like structure where it can have subcategories or subscripts.
• It's a logical grouping of different scripts and other categories.

Category syntax

• category: string (required)
  • Name of the category
  • ❗ Must be unique throughout the Collection
• children: [ Category | Script , ... ] (required)
  • ❗ Category must consist of at least one subcategory or script.
  • Children can be combination of scripts and subcategories.
• docs: string | [string, ... ]
  • Documentation pieces related to the category.
  • Rendered as markdown.

Script

• Script represents a single tweak.
• A script can be of two different types (just like functions):
  1. Inline script; a script with an inline code
     • Must define code property and optionally revertCode but not call
  2. Caller script; a script that calls other functions
     • Must define call property but not code or revertCode
• 🙏 For any new script, please add revertCode and docs values if possible.

Script syntax

• name: string (required)
  • Name of the script
  • ❗ Must be unique throughout the Collection
  • E.g. Disable targeted ads
• code: string (may be required)
  • Batch file commands that will be executed
  • 💡 If defined, best practice to also define revertCode
  • ❗ If not defined call must be defined, do not define if call is defined.
• revertCode: string
  • Code that'll undo the change done by code property.
  • E.g. let's say code sets an environment variable as setx POWERSHELL_TELEMETRY_OPTOUT 1
    • then revertCode should be doing setx POWERSHELL_TELEMETRY_OPTOUT 0
  • ❗ Do not define if call is defined.
• call: FunctionCall | [ FunctionCall , ... ] (may be required)
  • A shared function or sequence of functions to call (called in order)
  • ❗ If not defined code must be defined
• docs: string | [string, ... ]
  • Documentation pieces related to the script.
  • Rendered as markdown.
• recommend: "standard" | "strict" | undefined (default)
  • If not defined then the script will not be recommended
  • If defined it can be either
    • standard: Only non-breaking scripts without limiting OS functionality
    • strict: Scripts that can break certain functionality in favor of privacy and security

FunctionCall

• Describes a single call to a function by optionally providing values to its parameters.
• 👀 See parameter substitution for an example usage

FunctionCall syntax

• function: string (required)
  • Name of the function to call.
  • ❗ Function with same name must defined in functions property of Collection
• parameters: [ parameterName: parameterValue, ... ]

  • Defines key value dictionary for each parameter and its value

  • E.g.

      parameters:
        userDefinedParameterName: parameterValue
        # ...
        appName: Microsoft.WindowsFeedbackHub
    

  • 💡 Expressions (templating) can be used as parameter value

Function

• Functions allow re-usable code throughout the defined scripts.
• Functions are templates compiled by privacy.sexy and uses special expression expressions.
• A function can be of two different types (just like scripts):
  1. Inline function: a function with an inline code.
     • Must define code property and optionally revertCode but not call.
  2. Caller function: a function that calls other functions.
     • Must define call property but not code or revertCode.
• 👀 Read more on Templating for function expressions and example usages.

Function syntax

• name: string (required)
  • Name of the function that scripts will use.
  • Convention is to use camelCase, and be verbs.
  • E.g. uninstallStoreApp
  • ❗ Function names must be unique
• parameters: [ FunctionParameter , ... ]
  • List of parameters that function code refers to.
  • ❗ Must be defined to be able use in FunctionCall or expressions (templating) code: string (required if call is undefined)
  • Batch file commands that will be executed
  • 💡 Expressions (templating) can be used in its value
  • 💡 If defined, best practice to also define revertCode
  • ❗ If not defined call must be defined
• revertCode: string
  • Code that'll undo the change done by code property.
  • E.g. let's say code sets an environment variable as setx POWERSHELL_TELEMETRY_OPTOUT 1
    • then revertCode should be doing setx POWERSHELL_TELEMETRY_OPTOUT 0
  • 💡 Expressions (templating) can be used in code
• call: FunctionCall | [ FunctionCall , ... ] (may be required)
  • A shared function or sequence of functions to call (called in order)
  • The parameter values that are sent can use expressions (templating)
  • ❗ If not defined code must be defined

FunctionParameter

• Defines a parameter that function requires optionally or mandatory.
• Its arguments are provided by a Script through a FunctionCall.

FunctionParameter syntax

• name: string (required)
  • Name of the parameters that the function has.
  • Parameter names must be defined to be used in expressions (templating).
  • ❗ Parameter names must be unique and include alphanumeric characters only.
• optional: boolean (default: false)
  • Specifies whether the caller Script must provide any value for the parameter.
  • If set to false i.e. an argument value is not optional then it expects a non-empty value for the variable;
    • Otherwise it throws.
  • 💡 Set it to true if a parameter is used conditionally;
    • Or else set it to false for verbosity or do not define it as default value is false anyway.
  • 💡 Can be used in conjunction with with expression.

ScriptingDefinition

• Defines global properties for scripting that's used throughout its parent Collection.

ScriptingDefinition syntax

• language: string (required)
  • 📖 See ScriptingLanguage.ts enumeration for allowed values.
• startCode: string (required)
  • Code that'll be inserted on top of user created script.
  • Global variables such as $homepage, $version, $date can be used using parameter substitution code syntax such as Welcome to {{ $homepage }}!
• endCode: string (required)
  • Code that'll be inserted at the end of user created script.
  • Global variables such as $homepage, $version, $date can be used using parameter substitution code syntax such as Welcome to {{ $homepage }}!

Naming guidelines

• Prioritize consistency throughout all names.
• Use an instruction format like "do this, do that" for clear, direct guidance. This approach reduces potential confusion and offers easy-to-follow steps. It provides specific, unambiguous instructions.
• Ensure brand names adhere to their official casing.
• Choose clear and uncomplicated language.
• Favor the terms:
  • "Disable" over "Turn off"
  • "Configure" over "Set up"
  • "Clear" over "Erase" or "Clean"
  • "Minimize" over "Limit" or "Reduce" (when it enhances clarity)
  • "Remove" over "Uninstall"
• Structure your phrases for clarity.
  • For instance, "Disable XX telemetry" or "Clear XX data" are preferred over "Clear data from XX", "Disable telemetry in XX", or "Clear data of XX".
• Use sentence case rather than Title Case.