Integrate text on why we should use Pull Requests

[NeuroShepherd]

The text below was generated by ChatGPT 01 mini when asked about the advantages of using PRs in GitHub. The manual should:

• Provide the full text as a side note or collapsible section
• Provide a distilled version of these reasons, the ones most relevant to us, and be included in the main body of the manual

Also, consider integrating the GitHub for Beginners video playlist

Advantages of Using Pull Requests in GitHub

Pull requests (PRs) in GitHub offer several advantages, especially when it comes to collaboration, code quality, and project management. Here are some of the key benefits:

1. Code Review and Collaboration

• Peer Review: Pull requests allow team members to review each other's code before it’s merged into the main codebase. This helps catch bugs, improve code quality, and ensure consistency with coding standards.
• Discussion Thread: PRs provide a space for discussing code changes, asking questions, or suggesting improvements. It’s a more structured and visible way to communicate compared to informal messaging.
• Collaborative Improvements: Developers can comment on specific lines of code, offering suggestions or alternatives, which helps improve the overall quality of the codebase.

2. Version Control and History

• Clear Version History: PRs help keep track of what changes have been made and why, which is useful for understanding the evolution of a project. The PR can include detailed descriptions, links to issues or tasks, and relevant context.
• Traceability: Since each PR is tied to a unique commit or series of commits, it's easier to trace changes back to their origin, making debugging and auditing simpler.

3. Automatic Testing and Integration

• Continuous Integration (CI): Pull requests can trigger automated testing pipelines, ensuring that new changes don’t break existing functionality or introduce bugs. This helps maintain code quality without manual intervention.
• Preventing Breaking Changes: By running tests on every pull request, you can catch issues early, preventing problematic code from being merged into the main branch.

4. Branch Protection

• Controlled Merges: With PRs, you can enforce rules like requiring approval from one or more team members before merging, or requiring passing status checks (like tests) before changes can be merged.
• Protected Branches: In large teams or critical projects, you can set up branch protection rules, preventing direct pushes to important branches (like main or master) without going through a pull request review process.

5. Auditability and Transparency

• Clear Audit Trail: PRs provide a transparent record of the discussion, review, and approval process for each code change, making it easier to see who did what and why. This is especially valuable for larger teams or open-source projects.
• Visibility: Everyone can see the proposed changes, the discussions surrounding those changes, and any issues that were identified and resolved. This fosters a more open, collaborative development environment.

6. Preventing Mistakes and Reducing Risks

• Smaller, Manageable Changes: Pull requests typically contain smaller, self-contained changes that are easier to review and understand. This reduces the risk of introducing large, hard-to-review changes that may be difficult to debug or test.
• Reduced Conflicts: By regularly merging smaller PRs, conflicts with other team members’ work are easier to resolve, as opposed to a massive merge that could introduce multiple issues.

7. Improved Documentation

• Documenting Changes: PR descriptions can provide a detailed summary of the changes being made, including what’s fixed, new features, or refactors. This acts as documentation for future developers or when revisiting a part of the project after a long time.
• Linking to Issues: GitHub allows you to link pull requests to specific issues or feature requests, helping to track the context and progress of a task.

8. Code Quality Tools Integration

• Static Analysis & Linting: You can integrate tools that automatically analyze the code for style issues, security vulnerabilities, or performance problems when the pull request is created. This ensures the code adheres to best practices.

9. Managing Feature Flags or Experimental Work

• Feature Toggles: PRs can be used to introduce new features behind feature flags or toggles, allowing you to test new functionality without affecting the main production code.
• Work in Progress (WIP): Developers can mark pull requests as "Work in Progress" to signal that they are not ready to merge, giving teammates visibility into the state of the code.

10. Enhancing Project Management

• Tracking Progress: PRs can be linked to project boards, issues, or milestones. This helps with tracking the progress of a project and provides insight into what’s in progress, what’s done, and what’s blocked.
• Release Management: PRs often help streamline the release process by making it easier to isolate and group changes that should go into a specific release or version.

---

In summary, pull requests help streamline the development workflow, promote better collaboration, and ensure higher code quality. They also foster accountability and make managing changes more organized, especially when working with teams of any size.