Skip to content

Latest commit

 

History

History
192 lines (158 loc) · 9.54 KB

collection-files.md

File metadata and controls

192 lines (158 loc) · 9.54 KB
Raw

Collection files

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)
  • 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)
  • 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.