mirror of
https://github.com/ChrisTitusTech/winutil
synced 2026-06-04 14:17:27 +00:00
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
This commit is contained in:
Gabi
+119
-88
@@ -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
|
||||
irm https://christitus.com/windev | iex
|
||||
## Basic Git Workflow
|
||||
|
||||
### 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.
|
||||
|
||||
* 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;
|
||||
```bash
|
||||
git checkout -b feature-name
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
>
|
||||
> This is a diagram to guide you through the process. It may vary depending on the type of change you're making.
|
||||
Example:
|
||||
|
||||
### Fork the Repo
|
||||
* Fork the WinUtil Repository [here](https://github.com/ChrisTitusTech/winutil) to create a copy that will be available in your repository list.
|
||||
```bash
|
||||
git checkout -b add-firefox-tweak
|
||||
```
|
||||
|
||||
{{< image src="images/Fork-Button" alt="Fork Image" >}}
|
||||
---
|
||||
|
||||
### Clone the Fork
|
||||
> [!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.
|
||||
### 4. Edit the Code
|
||||
|
||||
* Install GitHub Desktop if it is not already installed.
|
||||
* 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.
|
||||
Open the project in your preferred text editor and make 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.
|
||||
* `cd {path to the folder with the compile.ps1}`
|
||||
* Run the following command to compile and run WinUtil:
|
||||
* `.\Compile.ps1 -run`
|
||||
Go to the project folder:
|
||||
|
||||
{{< 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
|
||||
* Before committing your changes, please discard changes made to the `winutil.ps1` file, like the following:
|
||||
```powershell
|
||||
.\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
|
||||
* 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.
|
||||
Check what changed:
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user