Win11Debloat/.github/CONTRIBUTING.md

# How to Contribute?

We welcome contributions from the community. You can contribute to Win11Debloat by:
- Reporting issues and bugs [here](https://github.com/Raphire/Win11Debloat/issues/new?template=bug_report.yml).
- Submitting feature requests [here](https://github.com/Raphire/Win11Debloat/issues/new?template=feature_request.yml)
- Testing Win11Debloat
- Creating a pull request
- Improving the documentation

# Testing Win11Debloat

You can help us test the latest changes and additions to the script. If you encounter any issues, please report them [here](https://github.com/Raphire/Win11Debloat/issues/new?template=bug_report.yml).

> [!WARNING]
> The prerelease version of Win11Debloat is meant for developers to test the script. Don't use this in production environments!

You can launch the prerelease version of Win11Debloat by running this command:
```ps1
& ([scriptblock]::Create((irm "https://debloat.raphi.re/dev")))
```

# Contributing Code

## Getting Started

### Fork and Clone the Repository

1. **Fork the project** on GitHub by clicking the "Fork" button at the top right of the repository page.

2. **Clone the repository** to your local machine:
   ```powershell
   git clone https://github.com/YOUR-USERNAME/Win11Debloat.git
   cd Win11Debloat
   ```

3. **Create a new branch** for your contribution:
   ```powershell
   git checkout -b feature/your-feature-name
   ```

### Running the Script Locally

1. Open PowerShell as an administrator
2. Enable script execution if necessary:
   ```powershell
   Set-ExecutionPolicy Unrestricted -Scope Process -Force
   ```
3. Navigate to your Win11Debloat directory
4. Run the script:
   ```powershell
   .\Win11Debloat.ps1
   ```

## Implementation Guidelines

### Project Structure

Understanding the project structure is essential for contributing effectively:

```
Win11Debloat/
├── Win11Debloat.ps1        # Main PowerShell script
├── Apps.json               # List of supported apps for removal
├── DefaultSettings.json    # Default configuration preset
├── LastUsedSettings.json   # Last used configuration (generated during use)
├── Assets/
│   └── Features.json       # All features with metadata
├── Regfiles/               # Registry files for each feature
├── Schemas/                # XAML Schemas for GUI elements
└── Scripts/                # Additional PowerShell scripts and functions
    └── Get.ps1             # Script used for the quick launch method to automatically download and run Win11debloat
```

### Best Practices

1. **Test Thoroughly**: Always test your changes on a Windows test environment before submitting.
2. **Document Changes**: Update the `README.md` and other relevant documentation. Wiki documentation will be generated/updated based on the `Features.json` and `Apps.json` files.
3. **Follow Existing Patterns**: Look at existing implementations for guidance.
4. **Use Clear Naming**: Choose descriptive names for features, IDs, and registry files.
5. **Provide All Registry Files**: Always create an `Undo` registry file for reversibility, aswell as a `Sysprep` registry file for Sysprep mode.
6. **Minimal Changes**: Registry files should only modify what's necessary.
7. **Comment Your Code**: Add comments explaining your reasoning for complex logic in PowerShell scripts.
8. **Version Constraints**: Use `MinVersion` and `MaxVersion` if a feature only applies to specific Windows versions.
9. **Limit pull requests to 1 feature**: Keep pull requests limited to just one feature, this makes it easier to review your changes.

### Code Style

- Use **4 spaces** for indentation in PowerShell scripts
- Use **2 spaces** for indentation in JSON files
- Follow existing naming conventions
- Keep lines reasonable in length
- Use descriptive variable names
- Try to limit your indentation to a max of 4-5 levels, if possible.
- Use [Segoe Fluent Icon Assets](https://learn.microsoft.com/en-us/windows/apps/design/iconography/segoe-fluent-icons-font) for icons.

### Testing Registry Changes

1. **Backup Registry**: Always create a system restore point
2. **Test Manually**: Test the registry changes manually first
3. **Verify Undo**: Test that the undo registry file properly reverts changes
4. **Verify Sysprep**: Test that the Sysprep registry file properly applies changes for new users
5. **Check Side Effects**: Ensure no unintended consequences

## Implementing New Features

### Adding Support for a New App

> [!NOTE]
> The script automatically generates the app options for the GUI from the app information in the Apps.json file.

To add a new app that can be removed via Win11Debloat:

1. **Find the AppId**: To find the correct AppId for an app:
   ```powershell
   Get-AppxPackage | Select-Object Name, PackageFullName
   ```

2. **Edit `Apps.json`**: Add a new entry to the `"Apps"` array:
   ```json
   {
     "FriendlyName": "Display Name",
     "AppId": "AppPackageIdentifier",
     "Description": "Brief description of the app",
     "SelectedByDefault": true|false
   }
   ```

3. **Guidelines**:
- Use clear, user-friendly names for `FriendlyName`
- Set `SelectedByDefault` to `true` only for apps that are largely considered bloatware, otherwise set to `false`
- Provide a concise description explaining what the app does

### Adding a New Feature

Features are defined in `Assets/Features.json` and can modify Windows settings via registry files or PowerShell commands.

> [!NOTE]
> For simple features that just include a registry change, no actual coding is required in the main script except for adding the corresponding command-line parameters. The GUI is automatically built using the information in the Features.json file.

#### 1a. Create the Registry File(s)

Create new registry files in the `Regfiles/` directory:

- **Disable file**: `Disable_YourFeature.reg`
- **Enable file**: `Undo/Enable_YourFeature.reg` (for reverting)
- **Sysprep file**: `Sysprep/Disable_YourFeature.reg` (for Sysprep mode)

Example registry file structure:
```reg
Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\YourPath]
"SettingName"=dword:00000000
```

A Sysprep registry file should apply the same changes as the normal action. Replace the hive of registry keys that start with `HKEY_CURRENT_USER` with `hkey_users\default`. For example:
```reg
Windows Registry Editor Version 5.00

[hkey_users\default\Software\Microsoft\Windows\CurrentVersion\YourPath]
"SettingName"=dword:00000000
```

#### 1b. Implement the Feature Logic

If your feature requires more than just applying a registry file, add custom logic to the main script in the appropriate section. In most cases this will involve creating a new entry in the `ExecuteParameter` function for your new feature.

#### 2. Add Feature to Features.json

Add your feature to the `"Features"` array in `Assets/Features.json`:

```json
{
  "FeatureId": "YourFeatureId",
  "Label": "Short label describing the feature",
  "ToolTip": "Detailed explanation of what this feature does and its impact.",
  "Category": "Privacy & Suggested Content",
  "Priority": 1,
  "Action": "Disable",
  "RegistryKey": "Disable_YourFeature.reg",
  "ApplyText": "Disabling your feature...",
  "UndoAction": "Enable",
  "RegistryUndoKey": "Enable_YourFeature.reg",
  "MinVersion": null,
  "MaxVersion": null
}
```

**Field Descriptions**:
- `FeatureId`: Unique identifier (must match parameter name in Win11Debloat.ps1 and Get.ps1)
- `Label`: Short description shown in the UI, written in a way to fit with the Action or UndoAction prefixed
- `ToolTip`: Detailed explanation of what the feature does, used for tooltips in the GUI
- `Category`: One of the predefined categories (see Categories array in Features.json)
- `Priority`: Optional. The priority value (int) is used to sort features within a category. If this field is omitted the feature will be sorted based on the order in the Features.json file.
- `Action`: Action word for the feature (e.g., "Disable", "Enable", "Hide", "Show")
- `RegistryKey`: Filename of the registry file to apply (in Regfiles/ directory) or null if feature does not require registry changes
- `ApplyText`: Message shown when applying the feature
- `UndoAction`: Action word for reverting (e.g., "Enable", "Show")
- `RegistryUndoKey`: Filename of the registry file to revert changes or null if feature does not require registry changes
- `MinVersion`: Minimum Windows build version (e.g., "22000") or null
- `MaxVersion`: Maximum Windows version or null

#### 3. Add Command-Line Parameter

Add a corresponding parameter to both `Win11Debloat.ps1` AND `Scripts/Get.ps1`, the parameter name should match the FeatureId you have defined in `Features.json`. In most cases this will be a switch parameter, example:
```powershell
[switch]$YourFeatureId,
```

### Adding a Category

To add a new category for organizing features:

- Add a new category entry to the `"Categories"` array in `Assets/Features.json`:
   ```json
   {
     "Name": "Your Category Name",
     "Icon": "&#xE#### ;"
   }
   ```

> [!TIP]
> Use [Segoe Fluent Icon Assets](https://learn.microsoft.com/en-us/windows/apps/design/iconography/segoe-fluent-icons-font) for icon codes.

### Adding UI Groups

UI Groups allow features to be grouped together in the GUI with a combobox (dropdown) selection:

```json
{
  "GroupId": "UniqueGroupId",
  "Label": "Display label for the group",
  "ToolTip": "Explanation of what this group controls",
  "Category": "Category Name",
  "Priority": 1,
  "Values": [
    {
      "Label": "Option 1",
      "FeatureIds": ["FeatureId1"]
    },
    {
      "Label": "Option 2",
      "FeatureIds": ["FeatureId2"]
    }
  ]
}
```

## Submitting a Pull Request

1. **Commit your changes** with clear, descriptive commit messages:
   ```powershell
   git add .
   git commit -m "Add feature: Description of your changes"
   ```

2. **Push to your fork**:
   ```powershell
   git push origin feature/your-feature-name
   ```

3. **Create a Pull Request** on GitHub:
   - Go to the original Win11Debloat repository
   - Click "New Pull Request"
   - Select your fork and branch
   - Provide a clear description of your changes
   - Reference any related issues

4. **Respond to feedback**: Be prepared to make adjustments based on code review feedback.

# Questions?

If you have questions about contributing, feel free to:
- Open a [discussion](https://github.com/Raphire/Win11Debloat/discussions)
- Comment on an existing issue
- Ask in your pull request