Tier2 CONTRIBUTING.md

[Ulrond]

Tier 2 Operator Guide: Forking for External Contributions

Introduction

Welcome to the Tier 2 Operator Guide! This guide is tailored for engineers and third-party contributors who want to enhance the project but don't have direct write access to the main repository. Forking is your key tool, enabling you to experiment and contribute without impacting the original codebase.

What is Forking?

Forking creates a personal copy of a repository on your own GitHub account. This copy is entirely independent, allowing you to modify the code freely without affecting the original project. It's like having your own sandbox to play in!

Why Fork?

• Safe Experimentation: Explore new ideas, fix bugs, or add features without the risk of breaking the main project.
• Contribution Pathway: Once your changes are ready, you can submit them as a pull request to the original repository for consideration.
• Open Source Collaboration: Forking is the cornerstone of open-source contribution, empowering individuals and teams to work together.

Step-by-Step Forking Workflow

1. Find the Repository: Locate the project's repository on GitHub.
2. Click "Fork": You'll find this button at the top right corner of the repository page.
3. Choose Destination: Select your GitHub account as the destination for the fork.
4. Clone Your Fork: Clone your newly created fork to your local machine using Git.

   git clone https://github.com/<your-username>/<repository-name>.git

5. Create a Branch: (Optional but recommended) Create a new branch for your specific changes. This keeps your work organized.

   git checkout -b feature/my-new-feature

6. Make Changes: Edit, add, or remove files as needed.
7. Commit Changes: Save your work regularly with clear and descriptive commit messages.

   git commit -m "Add new feature: <description>"

8. Push Changes: Upload your commits to your forked repository on GitHub.

   git push origin feature/my-new-feature

9. Create a Pull Request: Navigate to the original repository and click "New Pull Request." Select your fork and branch, then provide a detailed description of your changes.
10. Collaboration & Review: The maintainers of the original repository will review your pull request, offer feedback, and potentially merge your changes if they align with the project's goals.

Important Considerations

• Keep Your Fork Up-to-Date: Regularly sync your fork with the original repository to avoid conflicts.
• Clear Communication: In your pull request, clearly explain the purpose and benefits of your changes.
• Be Patient: The review process might take some time. Be open to feedback and iterate as needed.
• Respect Project Guidelines: Follow the project's coding conventions and contribution guidelines.

[mhughesacn]

Hi Gerald: Steve asked me to look at this. Two suggestions, for people who don't know git workflows well:

• What happens if you get feedback at step 10 and want to make changes? (i.e. Spell out what to do.)
• "Keep your fork up-to-date" - again, spell out what to do. What to do if there is a conflict?
  Thanks,
  Martin