How to Create a Pull Request (PR) from a Fork to the Original Repository

Overview

This guide provides a detailed, step-by-step process for contributing to an open-source project by creating a Pull Request (PR) from your fork to the original repository. It covers forking, making changes, syncing with the upstream repository, handling zip package updates, and submitting a well-documented PR.

---

Step 1: Fork the Original Repository

1. Navigate to the original repository on GitHub.
2. Click the Fork button in the top-right corner.
3. Choose your GitHub account as the destination for the fork.
4. Wait for GitHub to create a copy of the repository under your account.

Your fork is now an independent copy where you can make changes without affecting the original project.

---

Step 2: Clone Your Fork Locally

1. Go to your forked repository on GitHub.
2. Click the Code button and copy the URL (HTTPS or SSH).
3. Open your terminal and run:

   git clone <your-fork-url>
   cd <repo-name>
   

---

Step 3: Create a New Branch for Your Work

1. Always create a new branch for each feature or bugfix:

   git checkout -b my-feature-branch
   

2. Use a descriptive branch name (e.g., fix-typo-in-readme or feature/add-login-form).

---

Step 4: Make Changes and Test Locally

1. Implement your feature or bugfix in the codebase.
2. If the repository includes tests, run them to ensure your changes do not break anything:

   # Example for Python
   pytest
   # Example for Node.js
   npm test
   

3. If the repository contains a package as a zip file, make sure to update the files inside the zip as needed (see Step 7).

---

Step 5: Commit Your Changes

1. Stage and commit your changes with a clear, descriptive message:

   git add .
   git commit -m "Describe your changes here"
   

2. Make sure to follow the project’s commit message guidelines if provided.

---

Step 6: Sync Your Fork with the Original Repository (Upstream)

1. Add the original repository as an upstream remote (if not already done):

   git remote add upstream <original-repo-url>
   

2. Fetch the latest changes from the original repository:

   git fetch upstream
   

3. Merge the target branch (usually main or master) into your branch:

   git checkout my-feature-branch
   git merge upstream/main
   

4. Resolve any merge conflicts that arise. Test your code again after resolving conflicts.

---

Step 7: Update and Test Zip Package (If Applicable)

1. If the repository contains a package as a zip file (e.g., package/control-tower.zip):
   • Unzip the archive and update the necessary files with your changes and any new updates from the original repo.
   • Re-zip the package, ensuring all merged files are included.
2. Test the updated zip file if the project provides a way to do so (e.g., run a script or command to verify the package).

---

Step 8: Commit Updated Zip and Final Changes

1. Stage and commit the updated zip file and any other final changes:

   git add package/control-tower.zip
   git commit -m "Update control-tower.zip with merged changes"
   

---

Step 9: Push Changes to Your Fork

1. Push your branch to your forked repository:

   git push origin my-feature-branch
   

---

Step 10: Create a Pull Request to the Original Repository

1. Go to your fork on GitHub and switch to your feature branch.
2. Click the Compare & pull request button.
3. Ensure the base repository is the original repo and the base branch is correct (e.g., main).
4. Add a clear, detailed description of your changes:
   • List all features, fixes, and updates.
   • Mention if you updated a zip package and how you tested it.
   • Attach screenshots if relevant (e.g., test results, UI changes).
5. Submit the pull request.

---

Step 11: Ensure No Conflicts and Respond to Feedback

1. GitHub will automatically check for merge conflicts. If there are any, resolve them as described in Step 6.
2. Monitor your PR for feedback from maintainers. Respond to comments and make additional commits as needed.
3. Update your PR description if you make significant changes during review.

---

Step 12: Final Checklist Before Merge

• All tests pass
• No merge conflicts
• PR description is clear and complete
• Zip package (if any) is up to date and tested
• Screenshots or logs are attached if applicable

---

Tips and Best Practices

• Keep your branches focused on a single feature or fix.
• Regularly sync your fork with the upstream repository to minimize conflicts.
• Write clear commit messages and PR descriptions.
• Follow the project’s contribution guidelines.
• Be responsive to code review feedback.

---

By following these steps, you can efficiently contribute to Carrier platform and ensure your pull requests are easy to review and merge.