[ENH] Guides - Contribute: Request for GitHub Guide Enhancement: Working With GitHub for Oqtane Contributions

[thabaum]

Request for GitHub Guide Enhancement: Working With GitHub for Oqtane Contributions

---

Overview

The current GitHub guides for contributing to Oqtane documentation need significant enhancement. While existing resources provide some guidance, they do not cover essential Git workflows in sufficient detail. This gap leaves new contributors, especially those who may not work with GitHub daily, at a disadvantage. A comprehensive and user-friendly guide covering basic to intermediate Git workflows would enable contributors of all levels to contribute confidently and consistently.

To grow our community and foster effective contributions, we need standardized workflows and detailed instructions for the following key GitHub activities:

• Creating forks and understanding why they’re essential
• Managing branches to ensure isolated changes
• Setting up local directories
• Executing Git commands accurately
• Using GitHub’s web interface for simple edits vs. CLI for more complex PRs

This enhanced guide should cover best practices for forking, branching, committing, and opening pull requests. It should aim to eliminate the intimidation factor for contributors unfamiliar with GitHub by clearly explaining concepts in a structured, beginner-friendly way.

---

Proposed Outline of the Enhanced Guide

1. Introduction to the GitHub Contribution Workflow

   • Explain why contributing through GitHub is beneficial for the Oqtane project.
   • Outline the core tasks: forking the repo, branching, committing, and pull requests.

2. Simple Edits via GitHub Interface (Basic)

   • Step-by-step guide on making small edits (e.g., fixing typos, broken links).
   • How to navigate to a file, make changes, and commit directly through the GitHub web interface.

3. Setting Up a Local Git Environment (Intermediate)

   • Walkthrough for setting up Git on local machines.
   • Instructions for creating necessary local directories and cloning the Oqtane repository.

4. Forking and Cloning the Repository

   • Purpose of forking (keeping original repo intact).
   • Commands for cloning the forked repo to a local machine.
   • Common directories that help organize the cloned repo effectively.

5. Branching Best Practices

   • Why branching is essential for isolated changes.
   • Naming conventions for branches (e.g., feature-[description], docs-[description]).
   • Commands for creating and switching branches.

6. Making Changes and Committing Locally

   • How to make changes within a branch and commit them.
   • Guidelines for writing clear commit messages.
   • How to avoid unnecessary changes or commits.

7. Creating Pull Requests (PRs)

   • How to push changes to the forked repo and create a pull request.
   • Details on adding descriptions and comments to explain the changes.
   • How to check for errors and warnings before submitting PRs, especially for documentation.

8. Updating Forks and Branches (Keeping Up-to-Date)

   • Commands for syncing a fork with the upstream repository.
   • Instructions for managing branches and merging updates to prevent conflicts.

9. Reference Table for Common Git Commands

   • Summary table with commands and a brief description for each.
   • Include commands like git fetch, git pull, git rebase, and git merge.

10. Troubleshooting Tips

    • Common issues like merge conflicts and how to resolve them.
    • Link to relevant GitHub and Git documentation for deeper learning.

---

Why This Guide is Essential

To attract more contributors, documentation must be as accessible as possible. Expecting contributors to have advanced GitHub skills or to learn complex workflows independently is unrealistic. By providing clear, standardized instructions, we can encourage both new and experienced developers to contribute confidently.

This guide will also benefit developers working directly with Oqtane modules and extensions on GitHub. They’ll gain a better understanding of Git workflows, benefiting not only their contributions to Oqtane but also their personal projects or roles in open-source development.

---

Next Steps

By enhancing this guide, we will lower the barrier to entry for contributors, ensuring that all who wish to contribute feel empowered to do so. Additionally, a comprehensive reference like this can be a model for future guides within the Oqtane project, promoting a culture of clarity and inclusivity for all documentation efforts.

Thank you for considering this proposal!

[thabaum]

close to closing this, once I get more familiar... #91 will need some fine tooth combing by everyone I am hoping to make sure things are correct and properly documented first. I will work on this during the developer enhancements coming shortly as I start throwing down some module POC with Oqtane I can enhance this as well as after our upcoming doc meeting so we can discuss how to go about it along with all recent updates pushed into the new docs.

EDIT

To let the dust settle here I won't be doing any PR's until after the meeting to ensure things are working right while pushing. I want to do a PR at the meeting to see what we want to expect from contributors like myself. This one would be a good one we can work on doing together.

I will try to have a basic PR ready to go in Visual Studio, however we will from scratch copy paste those files to a PR we can record the steps and provide them in the PR.

This is to avoid the blasts of emails that may have came from recent PR's I submitted.

I never get this complaint when using the web interface to create a branch, and make changes to that branch in my fork and submit that as a PR.

However every time and in every way I have created a PR using Visual Studio Code I am hearing there is an issue. Even when I pushed it up to my branch first, and then made a PR. However I need to know if my comments and commits after that was done was the issue as I added some changes through the web interface. I could have worked on all the PR's I closed in one commit, but I closed a number of PR's which took updating 2 -3 files so 3 - 5 commits (emails) per PR closed.

I am wondering if these emails can't go to a folder like I have them go to keep your main inboxes clear. I get spammed all day from repo's otherwise. However it would be nice to know exactly what the issues are so they can be mentioned in this PR to help avoid spamming everyone watching this project.

I am not sure what permissions others have who get all the commit messages. I dont get commit messages from any I watch, only release from some and comments/discussions from others like Oqtane.Framework. So I know the notifications settings in GitHub can be setup differently per repo.