From e8adac185240e8ce4ffca82dd484b8cc8b0d2784 Mon Sep 17 00:00:00 2001 From: Raphire <9938813+Raphire@users.noreply.github.com> Date: Sun, 8 Mar 2026 01:03:44 +0100 Subject: [PATCH] Add CONTRIBUTING.md file --- .github/CONTRIBUTING.md | 276 ++++++++++++++++++++++++++++++++++++++++ README.md | 4 + 2 files changed, 280 insertions(+) create mode 100644 .github/CONTRIBUTING.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..81b9ded --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,276 @@ +# 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": "#### ;" + } + ``` + +> [!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 \ No newline at end of file diff --git a/README.md b/README.md index c3bf8a6..3326854 100755 --- a/README.md +++ b/README.md @@ -182,6 +182,10 @@ Below is an overview of the key features and functionality offered by Win11Deblo - Option to [apply changes to a different user](https://github.com/Raphire/Win11Debloat/wiki/Advanced-Features#running-as-another-user), instead of the currently logged in user. - [Sysprep mode](https://github.com/Raphire/Win11Debloat/wiki/Advanced-Features#sysprep-mode) to apply changes to the Windows Default user profile. Which ensures, all new users will have the changes automatically applied to them. +## Contributing + +We welcome contributions to Win11Debloat! Whether you'd like to report issues, suggest features, or submit code changes, please see our [Contributing Guidelines](/.github/CONTRIBUTING.md) for detailed instructions on how to get started and best practices for contributing. + ## License Win11Debloat is licensed under the MIT license. See the LICENSE file for more information.