Rework contributing.md (#4567)

* Delete docs/assets/images/Complie.png * Delete docs/assets/images/Commit-GHD.png * Delete docs/assets/images/Discard-GHD.png * Delete docs/assets/images/Push-Commit.png * Delete docs/assets/images/Fork-Button-Dark.png * Delete docs/assets/images/Fork-Button-Light.png * Update CONTRIBUTING.md * Update CONTRIBUTING.md * Update CONTRIBUTING.md * Update CONTRIBUTING.md * Update CONTRIBUTING.md * Update CONTRIBUTING.md
2026-06-04 14:17:27 +00:00 · 2026-05-28 10:32:27 -07:00
parent c99114e9e1
commit 076ef02b2c
8 changed files with 236 additions and 175 deletions
@@ -1,119 +1,149 @@
-# How to Contribute?
+## Contributing Code
-## Testing
+### Before You Start
-* Test the latest changes to WinUtil by running the pre-release and reporting issues you are encountering to help us continually improve WinUtil!
+- Keep each pull request focused on a single feature or fix.
 - Avoid unnecessary formatting changes or large unrelated edits.
 - Document what changed and why in your PR description.
-#### **Run the latest pre-release**
+---
   ```ps1
   irm https://christitus.com/windev | iex
   ```
-!!! bug "Keep in mind"
+## Basic Git Workflow
-     This is a pre-release and should be treated as such. It exists for developers to test the utility and report or fix bugs before they get added to the stable release. Don't use it in production!
+### 1. Fork the Repository
-## Issues
+Go to the ChrisTitusTech/winutil repository on GitHub and click the Fork button in the top right corner.
-* If you encounter any challenges or problems with the script, I kindly request that you submit them via the "Issues" tab on the GitHub repository. By filling out the provided template, you can provide specific details about the issue, allowing me (and others in the community) to promptly address any bugs or consider feature requests.
+<img width="171" height="50" alt="{650A4723-F38A-44A4-9820-D232BC87C8A0}" src="https://github.com/user-attachments/assets/a214f27c-2fee-444a-920f-d87b14f5896f" />
-## Contribute Code
+---
-* Pull requests are now handled directly on the **MAIN branch**. This was done since we can now select specific releases to launch via releases in GitHub.
+### 2. Clone Your Fork
-* If you're doing code changes, then you can submit a PR to the `main` branch.
+```powershell
-
+git clone https://github.com/YOUR_USERNAME/winutil.git
-!!! warning "Important"
+cd winutil
     Do not use a code formatter, make massive amounts of line changes, or make multiple feature changes. EACH FEATURE CHANGE SHOULD BE IT'S OWN PULL REQUEST!
     Do not open a pull request that adds support for other languages to WinUtil for now, until we decide how we want to move forward with language support.
 * When creating pull requests, it is essential to thoroughly document all changes made. This includes, but is not limited to, documenting any additions made to the `tweaks` section and corresponding `undo tweak`, so users are able to remove the newly added tweaks if necessary, and comprehensive documentation is required for all code changes. Document your changes and briefly explain why you made your changes in your Pull Request Description. Failure to adhere to this format may result in the denial of the pull request. Additionally, any code lacking sufficient documentation may also be denied.
 * By following these guidelines, we can maintain a high standard of quality and ensure that the codebase remains organized and well-documented.
 !!! note
     When creating a function, please include "WPF" or "WinUtil" in the file name so it can be loaded into the runspace.
 ## Walk through
 * This is a guide for beginners. If you are still having issues, look at the following official GitHub documentation:
    * [Commit through WEB](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/about-commits)
    * [Commit through GitHub Desktop](https://docs.github.com/en/desktop/making-changes-in-a-branch/committing-and-reviewing-changes-to-your-project-in-github-desktop#about-commits)
    * [Create a Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)
 ### Overview
 ``` mermaid
 %%{init: {"flowchart": {"curve": "cardinal"}} }%%
 graph TD
   A[Fork Project] --> B[Clone Repository];
   B --> C[Create New Branch];
   C --> D[Make Changes];
   D --> G[Test Changes];
   G --> H{Tests Passed?};
   H -->|Yes| E[Commit Changes];
   H -->|No| J[Fix Issues];
   J --> G;
   E --> F[Push Branch];
   F --> K[Create Pull Request];
   K --> L[Fill out PR template];
  classDef default stroke:#333,stroke-width:4px,font-size:12pt;
 ```
 !!! info
-     This is a diagram to guide you through the process. It may vary depending on the type of change you're making.
+---
-### Fork the Repo
+### 3. Create a Branch
 * Fork the WinUtil Repository [here](https://github.com/ChrisTitusTech/winutil) to create a copy that will be available in your repository list.
-![Fork Image](/docs/assets/images/Fork-Button-Dark.png#gh-dark-mode-only)
+Never work directly on `main`.
-![Fork Image](/docs/assets/images/Fork-Button-Light.png#only-light#gh-light-mode-only)
+Create a branch related to your change:
-### Clone the Fork
+```powershell
-!!! tip
+git checkout -b feature-name
 ```
-     While you can make your changes directly through the Web, we recommend cloning the repo to your device using the application GitHub Desktop (available in WinUtil) to test your fork easily.
+Example:
-* Install GitHub Desktop if it is not already installed.
+```powershell
-* Log in using the same GitHub account you used to fork WinUtil.
+git checkout -b add-firefox-tweak
-* Choose the fork under "Your Repositories" and press "clone {repo name}"
+```
 * Create a new branch and name it something relatable to your changes.
-* Now you can modify WinUtil to your liking using your preferred text editor.
+---
 ### 4. Edit the Code
-### Testing your changes
+Open the project in your preferred text editor and make your changes.
-* To test to see if your changes work as intended, run the following commands in a PowerShell terminal as admin:
+Keep changes small and focused.
-* Change the directory where you are running the commands to the forked project.
+---
 * `cd {path to the folder with the compile.ps1}`
 * Run the following command to compile and run WinUtil:
 * `.\Compile.ps1 -run`
-![Compile](/docs/assets/images/Complie.png)
+### 5. Test Your Changes
-* After seeing that your changes work properly, feel free to commit the changes to the repository and make a PR. For help on that, follow the documentation below.
+Open Pwsh (Not Powershell) as Administrator.
-### Committing the changes
+Go to the project folder:
 * Before committing your changes, please discard changes made to the `winutil.ps1` file, like the following:
-![Push Commit Image](/docs/assets/images/Discard-GHD.png)
+```powershell
 cd path\to\winutil
 ```
-* Now, commit your changes once you are happy with the result.
+Run:
-![Commit Image](/docs/assets/images/Commit-GHD.png)
+```powershell
 .\Compile.ps1 -Run
 ```
-* Push the changes to upload them to your fork on github.com.
+Verify:
-![Push Commit Image](/docs/assets/images/Push-Commit.png)
+- WinUtil launches correctly
 - Your feature works
 - Nothing else breaks
-### Making a PR
+If something fails, fix it before committing.
-* To make a PR on your repo under a new branch linking to the main branch, a button will show and say Preview and Create pull request. Click that button and fill in all the information that is provided on the template. Once all the information is filled in correctly, check your PR to make sure there is no WinUtil.ps1 file attached to the PR. Once everything is good, make the PR and wait for Chris (the maintainer) to accept or deny your PR. Once it is accepted by Chris, you will be able to see your changes in the "/windev" build.
+
-* If you do not see your feature in the main "/win" build, that is fine. All new changes go into the /windev build to make sure everything is working OK before going fully public.
+---
-* Congratulations! You just submitted your first PR. Thank you so much for contributing to WinUtil.
+
 ### 6. Review Your Changes
 Check what changed:
 ```powershell
 git status
 ```
 Review the diff:
 ```powershell
 git diff
 ```
 Make sure you did not accidentally modify unrelated files.
 ---
 ### 7. Commit Your Changes
 Stage files:
 ```powershell
 git add .
 ```
 Commit them:
 ```powershell
 git commit -m "Add feature description"
 ```
 Example:
 ```powershell
 git commit -m "Add Firefox package tweak"
 ```
 ---
 ### 8. Push Your Branch
 ```powershell
 git push origin branch-name
 ```
 Example:
 ```powershell
 git push origin add-firefox-tweak
 ```
 ---
 ### 9. Open a Pull Request
 Go to your fork on GitHub.
 GitHub will show a button to create a pull request.
 <img width="1009" height="71" alt="{C8C6A3CC-79D4-44FD-A54C-4C5717F12730}" src="https://github.com/user-attachments/assets/0419d193-d4e7-47c0-87cf-b986742201a0" />
 Before submitting:
 - Explain what changed
 - Explain why you changed it
 - Make sure unrelated files are not included
 Once submitted, maintainers will review your PR.
@@ -2,121 +2,152 @@
 toc: true
 ---
-# How to Contribute?
+## Contributing Code
-## Testing
+### Before You Start
-* Test the latest changes to WinUtil by running the pre-release and reporting issues you are encountering to help us continually improve WinUtil!
+- Keep each pull request focused on a single feature or fix.
 - Avoid unnecessary formatting changes or large unrelated edits.
 - Document what changed and why in your PR description.
-#### Run the latest pre-release
+---
-```ps1
+## Basic Git Workflow
-irm https://christitus.com/windev | iex
+
 ### 1. Fork the Repository
 Go to the ChrisTitusTech/winutil repository on GitHub and click the Fork button in the top right corner.
 <img width="171" height="50" alt="{650A4723-F38A-44A4-9820-D232BC87C8A0}" src="https://github.com/user-attachments/assets/a214f27c-2fee-444a-920f-d87b14f5896f" />
 ---
 ### 2. Clone Your Fork
 ```bash
 git clone https://github.com/YOUR_USERNAME/winutil.git
 cd winutil
 ```
-> [!IMPORTANT]
+---
 > **Keep in mind** That this is a pre-release and should be treated as such. It exists for developers to test the utility and report or fix bugs before they get added to the stable release. Don't use it in production!
-## Issues
+### 3. Create a Branch
-* If you encounter any challenges or problems with the script, I kindly request that you submit them via the "Issues" tab on the GitHub repository. By filling out the provided template, you can provide specific details about the issue, allowing me (and others in the community) to promptly address any bugs or consider feature requests.
+Never work directly on `main`.
-## Contribute Code
+Create a branch related to your change:
-* Pull requests are now handled directly on the **MAIN branch**. This was done since we can now select specific releases to launch via releases in GitHub.
+```bash
-
+git checkout -b feature-name
 * If you're doing code changes, then you can submit a PR to the `main` branch.
 > [!IMPORTANT]
 > Do not use a code formatter, make massive amounts of line changes, or make multiple feature changes. EACH FEATURE CHANGE SHOULD BE IT'S OWN PULL REQUEST!
 > [!IMPORTANT]
 > Do not open a pull request that adds support for other languages to WinUtil for now, until we decide how we want to move forward with language support.
 * When creating pull requests, it is essential to thoroughly document all changes made. This includes, but is not limited to, documenting any additions made to the `tweaks` section and corresponding `undo tweak`, so users are able to remove the newly added tweaks if necessary, and comprehensive documentation is required for all code changes. Document your changes and briefly explain why you made your changes in your Pull Request Description. Failure to adhere to this format may result in the denial of the pull request. Additionally, any code lacking sufficient documentation may also be denied.
 * By following these guidelines, we can maintain a high standard of quality and ensure that the codebase remains organized and well-documented.
 > [!NOTE]
 >
 > When creating a function, please include "WPF" or "WinUtil" in the file name so it can be loaded into the runspace.
 ## Walk through
 * This is a guide for beginners. If you are still having issues, look at the following official GitHub documentation:
    * [Commit through WEB](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/about-commits)
    * [Commit through GitHub Desktop](https://docs.github.com/en/desktop/making-changes-in-a-branch/committing-and-reviewing-changes-to-your-project-in-github-desktop#about-commits)
    * [Create a Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)
 ### Overview
 ```mermaid
 %%{init: {"flowchart": {"curve": "cardinal"}} }%%
 graph TD
     A[Fork Project] --> B[Clone Repository];
     B --> C[Create New Branch];
     C --> D[Make Changes];
     D --> G[Test Changes];
     G --> H{Tests Passed?};
     H -->|Yes| E[Commit Changes];
     H -->|No| J[Fix Issues];
     J --> G;
     E --> F[Push Branch];
     F --> K[Create Pull Request];
     K --> L[Fill out PR template];
  classDef default stroke:#333,stroke-width:4px,font-size:12pt;
 ```
-> [!NOTE]
+Example:
 >
 > This is a diagram to guide you through the process. It may vary depending on the type of change you're making.
-### Fork the Repo
+```bash
-* Fork the WinUtil Repository [here](https://github.com/ChrisTitusTech/winutil) to create a copy that will be available in your repository list.
+git checkout -b add-firefox-tweak
 ```
-{{< image src="images/Fork-Button" alt="Fork Image" >}}
+---
-### Clone the Fork
+### 4. Edit the Code
 > [!TIP]
 >
 > While you can make your changes directly through the Web, we recommend cloning the repo to your device using the application GitHub Desktop (available in WinUtil) to test your fork easily.
-* Install GitHub Desktop if it is not already installed.
+Open the project in your preferred text editor and make your changes.
 * Log in using the same GitHub account you used to fork WinUtil.
 * Choose the fork under "Your Repositories" and press "clone {repo name}"
 * Create a new branch and name it something relatable to your changes.
-* Now you can modify WinUtil to your liking using your preferred text editor.
+Keep changes small and focused.
 ---
-### Testing your changes
+### 5. Test Your Changes
-* To test to see if your changes work as intended, run the following commands in a PowerShell terminal as admin:
+Open PowerShell as Administrator.
-* Change the directory where you are running the commands to the forked project.
+Go to the project folder:
 * `cd {path to the folder with the compile.ps1}`
 * Run the following command to compile and run WinUtil:
 * `.\Compile.ps1 -run`
-{{< image src="images/Complie" alt="Compile" >}}
+```powershell
 cd path\to\winutil
 ```
-* After seeing that your changes work properly, feel free to commit the changes to the repository and make a PR. For help on that, follow the documentation below.
+Run:
-### Committing the changes
+```powershell
-* Before committing your changes, please discard changes made to the `winutil.ps1` file, like the following:
+.\Compile.ps1 -Run
 ```
-{{< image src="images/Discard-GHD" alt="Push Commit Image" >}}
+Verify:
-* Now, commit your changes once you are happy with the result.
+- WinUtil launches correctly
 - Your feature works
 - Nothing else breaks
-{{< image src="images/Commit-GHD" alt="Commit Image" >}}
+If something fails, fix it before committing.
-* Push the changes to upload them to your fork on github.com.
+---
-{{< image src="images/Push-Commit" alt="Push Commit Image" >}}
+### 6. Review Your Changes
-### Making a PR
+Check what changed:
-* To make a PR on your repo under a new branch linking to the main branch, a button will show and say Preview and Create pull request. Click that button and fill in all the information that is provided on the template. Once all the information is filled in correctly, check your PR to make sure there is no WinUtil.ps1 file attached to the PR. Once everything is good, make the PR and wait for Chris (the maintainer) to accept or deny your PR. Once it is accepted by Chris, you will be able to see your changes in the "/windev" build.
+
-* If you do not see your feature in the main "/win" build, that is fine. All new changes go into the /windev build to make sure everything is working OK before going fully public.
+```bash
-* Congratulations! You just submitted your first PR. Thank you so much for contributing to WinUtil.
+git status
 ```
 Review the diff:
 ```bash
 git diff
 ```
 Make sure you did not accidentally modify unrelated files.
 ---
 ### 7. Commit Your Changes
 Stage files:
 ```bash
 git add .
 ```
 Commit them:
 ```bash
 git commit -m "Add feature description"
 ```
 Example:
 ```bash
 git commit -m "Add Firefox package tweak"
 ```
 ---
 ### 8. Push Your Branch
 ```bash
 git push origin branch-name
 ```
 Example:
 ```bash
 git push origin add-firefox-tweak
 ```
 ---
 ### 9. Open a Pull Request
 Go to your fork on GitHub.
 GitHub will show a button to create a pull request.
 <img width="1009" height="71" alt="{C8C6A3CC-79D4-44FD-A54C-4C5717F12730}" src="https://github.com/user-attachments/assets/0419d193-d4e7-47c0-87cf-b986742201a0" />
 Before submitting:
 - Explain what changed
 - Explain why you changed it
 - Make sure unrelated files are not included
 Once submitted, maintainers will review your PR.