MidasTechnologiesInc/MidasEngine
3
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
Files
8a7f5a7a8fbf3c6a2a667ca01a308f5746ae9f23
MidasEngine/docs/PoliciesAndStandards/GitAndGithubStandards.md

33 KiB
Raw Blame History

# Git and GitHub Standards

Table of Contents

  1. Overview
  2. Understanding Git and GitHub
  3. Branching Strategy
  4. Branch Naming Conventions
  5. Commit Message Standards
  6. Code Review Policy
  7. Best Practices for Using Git
  8. Working with Pull Requests
  9. File-Path Standards

Overview

This document provides a comprehensive set of standards and best practices for using Git and GitHub within our development team. It covers foundational topics, including the branching strategy, branch naming conventions, commit message guidelines, code review policies, and collaboration workflows. The goal is to maintain a consistent and organized approach to version control, improve collaboration, ensure code quality, and streamline the development process.

The guidelines in this document are designed to help both new and experienced team members align with the company's coding and collaboration standards, facilitating smoother project management and code integrity.

Git and GitHub: A Comprehensive Guide

Table of Contents

  1. Introduction
  2. Understanding Version Control
  3. Git Basics
  4. Getting Started with Git
  5. Git Essentials
  6. Introduction to GitHub
  7. Working with Repositories on GitHub
  8. Git and GitHub Workflow
  9. Git Commands in Depth
  10. Advanced Git Techniques
  11. Common Mistakes and How to Avoid Them

Introduction

Git and GitHub are essential tools in the modern development landscape, allowing developers to manage changes, work collaboratively, and maintain robust codebases. Git is a distributed version control system that tracks code history, while GitHub enhances this by offering a platform for hosting, reviewing, and managing projects.

This guide delves into both Git and GitHub, providing an extensive overview that covers everything from beginner concepts to advanced techniques and command usage.

Understanding Version Control

Version Control is the backbone of any collaborative software development project. It allows teams to track code changes, collaborate seamlessly, and maintain a history of modifications to revert to previous versions when needed.

Types of Version Control

  1. Local Version Control: Simple, single-machine control, not suitable for team environments.
  2. Centralized Version Control (CVCS): Stores all file versions on a central server (e.g., SVN).
  3. Distributed Version Control (DVCS): Each team member has a full copy of the history and the latest version of the project, with Git being the most prominent DVCS.

Git is distributed, so it allows every developer to maintain a complete copy of the codebase on their own system, making collaboration more resilient and flexible.

Git Basics

What is Git?

Git is a distributed version control system (DVCS) designed to handle projects of all sizes efficiently. It tracks changes to files, enabling developers to manage, review, and revert code.

Core Concepts of Git

  1. Repository: A collection of files, folders, and their complete revision history.
  2. Commit: A snapshot of changes with a unique identifier (hash).
  3. Branch: A separate line of development within a repository.
  4. Merge: Combines changes from one branch into another, either to incorporate new features or resolve conflicts.
  5. Pull Request (PR): A request to merge changes from one branch into another with a code review.

Getting Started with Git

Installing Git

To start using Git, install it on your local system:

  • Linux: sudo apt-get install git
  • macOS: brew install git
  • Windows: Download from Git’s website.

Configuring Git

Set up your name and email, which will be attached to your commits:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

To verify configurations:

git config --list

Git Essentials

Repositories

A repository (repo) is the core structure of any Git project. It includes all project files, a history of changes, and branch information.

Staging and Committing

  1. Staging: The process of adding files to the staging area to prepare them for a commit.
  2. Committing: Saves a snapshot of the staged changes in the repository with a unique identifier and message.

Basic workflow:

git add <filename>    # Stage changes
git commit -m "Add description of changes"  # Commit staged changes

Branches and Merging

Branches let you create separate environments for development, allowing you to work on features without affecting the main codebase. Merging incorporates changes from one branch into another.

git branch <branch-name>       # Create a new branch
git checkout <branch-name>     # Switch to that branch
git merge <branch-name>        # Merge branch into current branch

Introduction to GitHub

What is GitHub?

GitHub is a cloud-based platform for Git repositories, providing tools for collaboration, code review, and project management.

Key Features of GitHub

  • Pull Requests: Propose and discuss changes before merging.
  • Issues: Track bugs and feature requests.
  • GitHub Actions: Automate workflows for CI/CD.
  • Project Boards: Visual task management using Kanban-style boards.

Working with Repositories on GitHub

  1. Creating a Repository: Go to GitHub and create a new repository for your project.
  2. Cloning a Repository: Copy a repository to your local machine with git clone <repo-url>.
  3. Syncing with Remote: Use git pull to fetch and merge changes from the remote repo and git push to upload changes.

Git and GitHub Workflow

Forking and Cloning

Forking allows you to create a copy of another user’s repository, letting you make changes without affecting the original. Cloning copies a remote repository to your local machine.

Pull Requests and Code Reviews

  • Opening a PR: After pushing changes to a branch, create a PR on GitHub to propose merging them into the main branch.
  • Code Reviews: Collaborators can provide feedback, request changes, or approve the PR.

GitHub Issues and Project Management

GitHub offers Issues to track development tasks and Project Boards to organize these issues visually.

Git Commands in Depth

Working with Commits

  • View Commit History: git log shows a detailed history of commits.
  • Viewing Differences: git diff displays changes between commits or branches.
  • Amending a Commit: Modify the last commit with git commit --amend.

Branch Management

  • List Branches: git branch shows all branches.
  • Delete a Branch: git branch -d <branch-name> removes a local branch.
  • Rename a Branch: git branch -m <new-name> renames the current branch.

Merging Branches

Merging integrates changes from one branch to another. Use git merge <branch-name> to combine changes into the current branch.

Rebasing

Rebasing applies commits from one branch onto another, maintaining a linear history:

git rebase <branch-name>

Resetting and Reverting

  • Resetting: Moves the repository to a previous state. 
    git reset --hard <commit-hash>  # Discards all changes
git reset --soft <commit-hash>  # Keeps changes in staging
  • Reverting: Undoes a commit by creating a new commit. 
    git revert <commit-hash>

Stashing

Stashing lets you save changes temporarily without committing:

git stash          # Save changes
git stash apply    # Restore stashed changes

Cherry-Picking

Cherry-picking applies a specific commit from one branch onto another:

git cherry-pick <commit-hash>

Synchronizing with Remotes

  • Fetch: git fetch downloads updates from the remote repository.
  • Pull: git pull combines fetch and merge.
  • Push: git push uploads local changes to the remote repository.

Advanced Git Techniques

Git Aliases

Aliases can simplify complex Git commands:

git config --global alias.st status
git config --global alias.cm commit

Interactive Rebase

Interactive rebasing allows you to reorder, squash, or edit commits:

git rebase -i <base-commit>

Common Mistakes and How to Avoid Them

Forgetting to Stage Changes

If you forget to git add your changes, they won’t be included in your commit. Always check with git status before committing.

Overwriting History with Rebase

Rebasing can rewrite history, so it’s recommended to avoid it on branches shared with others. Only rebase

branches that haven’t been pushed or that you’re working on independently.

Ignoring Merge Conflicts

When merging branches, conflicts may arise. Don’t skip or ignore these! Use a merge tool or manually resolve conflicts, and make sure to commit the resolved changes.

Accidental Commits to the Wrong Branch

Switching branches without committing or stashing changes can result in accidental commits. Always check your branch with git branch before committing and use git stash to save uncommitted changes if you need to switch.

Pushing Sensitive Information

Never commit sensitive data like passwords, API keys, or credentials. Use a .gitignore file to exclude sensitive files and directories:

echo "config.json" >> .gitignore

Force Pushing

Using git push --force can overwrite others' work. Only use --force when absolutely necessary, and communicate with your team beforehand. I have removed --force capabilitys on the github

Branching Structure and Naming Conventions

Purpose

This document establishes standards for creating, naming, and managing branches within our repository. Following these guidelines will ensure a clean, organized codebase, making it easier for the team to manage code changes, facilitate collaboration, and maintain clarity across multiple projects.

Table of Contents

  1. Branch Structure
  2. Branch Naming Conventions
  3. File Naming Standards
  4. Workflow for Contributors

Branch Structure

Our repository follows a structured branching system with two main branches, main and dev, along with various feature and ad-hoc branches off dev for specific tasks. All branches off dev should be named according to the conventions defined in this document.

1. main Branch

  • Purpose: The main branch contains production-ready code. This is where stable, tested code resides and reflects the latest release version of the codebase.
  • Access: Only project maintainers can directly merge code into main.
  • Merges: Code merges into main should always come from dev after passing code reviews and tests.
  • Protection: This branch is protected by branch rules, requiring code reviews and successful checks before merging.

2. dev Branch

  • Purpose: The dev branch is a staging branch for testing new features, bug fixes, and documentation updates before they reach main.
  • Access: All contributors can create branches off dev for their work. Contributors are not allowed to push directly to dev; all changes must be submitted via pull requests.
  • Merges: All feature, bugfix, documentation, and test branches should be merged back into dev after review and testing.

3. Feature and Ad-Hoc Branches

  • Purpose: Branches off dev are used for specific features, bug fixes, testing updates, and documentation changes. These branches must follow the naming conventions detailed in the following section.
  • Lifecycle: Feature and ad-hoc branches are created for individual tasks and are short-lived. Once their purpose is completed, they are merged into dev and deleted.
  • Permissions: Contributors create, work on, and manage these branches off dev but must submit pull requests (PRs) for all changes to dev.

Note

: Only the GitHub repository manager may deviate from these conventions.

Branch Naming Conventions

To maintain organization and readability, all branches off dev must follow these naming conventions. Standard prefixes indicate the branch's purpose and scope, providing clarity to other contributors.

General Rules

  • Lowercase Only: Branch names must be in lowercase.
  • Hyphens for Separation: Use hyphens (-) to separate words within a branch name.
  • Descriptive Names: Branch names should indicate the purpose of the branch (e.g., feature, bugfix) and include an identifier if relevant.
  • Reference to Issue/Feature Numbers: When applicable, include a reference to the GitHub issue number.

Prefixes

Prefix Purpose Example
feature/ For new features or enhancements feature/user-authentication
bugfix/ For fixing known bugs or issues bugfix/1023-login-error
docs/ For documentation updates and additions docs/api-endpoints-documentation
test/ For changes or additions to tests test/add-unit-tests
hotfix/ For critical fixes that need immediate attention in dev or main hotfix/production-fix-login-error

Note

: All prefixes indicate branches off dev and should not directly branch from main without repository manager approval.

Branch Names, Scenarios and Examples

Purpose Branch Name Description
New Feature feature/user-registration Adds user registration functionality
Bug Fix bugfix/215-api-authorization Fixes authorization issue on API requests
Documentation docs/setup-instructions Adds setup instructions to documentation
Testing test/integration-test-api Adds integration tests for API endpoints
Hotfix hotfix/cache-issue Urgent fix for cache-related issue

When working on specific aspects of the project, contributors should use designated branches to ensure consistency and organization. All branches, unless specified, must be created off the dev branch. Below are common scenarios and the appropriate branches for each task:

1. Adding a Web Scraper

  • Branch: DataCollection (branch off dev)
  • Process:
    • Begin by switching to the dev branch: 
      git checkout dev
git pull origin dev
    • Check out the DataCollection branch: 
      git checkout DataCollection
    • If DataCollection does not exist, create it off dev: 
      git checkout -b DataCollection dev
git push -u origin DataCollection

2. Adding Documentation

  • Branch: docs (branch off dev)
  • Process:
    • Switch to the dev branch and pull the latest updates: 
      git checkout dev
git pull origin dev
    • Check out the docs branch: 
      git checkout docs
    • If docs does not exist, create it off dev: 
      git checkout -b docs dev
git push -u origin docs

3. Adding Business Files

  • Branch: businessfiles (branch off dev)
  • Process:
    • Ensure you’re working from the latest dev updates: 
      git checkout dev
git pull origin dev
    • Check out the businessfiles branch: 
      git checkout businessfiles
    • If businessfiles does not exist, create it off dev: 
      git checkout -b businessfiles dev
git push -u origin businessfiles

4. Bug Fixes

  • Branch: bugfix (branch off dev)
  • Process:
    • Start from the latest dev updates: 
      git checkout dev
git pull origin dev
    • Check out the bugfix branch: 
      git checkout bugfix
    • If bugfix does not exist, create it: 
      git checkout -b bugfix dev
git push -u origin bugfix

5. Hotfixes

  • Branch: hotfix (branch off dev)
  • Process:
    • Ensure your local dev branch is up to date: 
      git checkout dev
git pull origin dev
    • Check out the hotfix branch: 
      git checkout hotfix
    • If hotfix does not exist, create it: 
      git checkout -b hotfix dev
git push -u origin hotfix

6. Testing

  • Branch: testing (branch off dev)
  • Process:
    • Start from the latest dev branch: 
      git checkout dev
git pull origin dev
    • Check out the testing branch: 
      git checkout testing
    • If testing does not exist, create it: 
      git checkout -b testing dev
git push -u origin testing

7. Feature Development

  • Branch: feature/feature-name (branch off dev)
  • Process:
    • Before starting, always check if a specific feature branch exists.
    • If no specific branch exists, create a new feature branch off dev: 
      git checkout dev
git pull origin dev
git checkout -b feature/your-feature-name dev
git push -u origin feature/your-feature-name
    • Note: Follow the naming conventions for all feature branches and verify it branches off dev.

Handling Merge Conflicts

Merge conflicts can occur when changes in two branches affect the same lines of code. Here are best practices and commands to resolve them effectively.

Steps to Resolve Merge Conflicts

  1. Identify the Conflict:

    • When attempting to merge, Git will notify you of conflicts. Use the git status command to identify files with conflicts: 
      git status

  2. Open and Review Conflicting Files:

    • Open the conflicting files in an editor. Git marks conflicts with <<<<<<<, =======, and >>>>>>>.
    • Manually review the changes, decide which version to keep, or combine changes where necessary.

  3. Mark Conflicts as Resolved:

    • After resolving conflicts in each file, mark it as resolved: 
      git add <file-name>

  4. Complete the Merge:

    • Once all conflicts are resolved, commit the merge: 
      git commit

  5. Push the Resolved Branch:

    • After committing, push the branch to the remote repository: 
      git push

Best Practices for Conflict Resolution

  • Resolve Locally: If possible, resolve conflicts on your local machine to minimize errors and ensure all changes are reviewed.
  • Communicate with Team Members: If the conflict is complex or affects significant code, communicate with the involved team members for clarity and to avoid overwriting important changes.
  • Use Git Tools for Assistance: Tools like git diff and git log are helpful for understanding changes in context. Additionally, many IDEs offer merge tools that visualize conflicts.

File Naming Standards

To maintain a consistent and organized structure, file names should follow these standards based on file type.

Documentation Files

  • Capitalized Case: Use Capitalized Case for documentation files (e.g., GitAndGitHubStandards.md).
  • Avoid Special Characters: Do not use spaces or special characters.
  • Location: Documentation related to each project should be stored within a docs/ or documentation/ directory in the root of each project.

Code Files

  • Lowercase with Underscores: Use lowercase names with underscores (e.g., user_authentication.py).
  • No Spaces or Special Characters: Avoid spaces or special characters in code file names.
  • Descriptive Names: Name files according to their primary function or feature (e.g., data_processing.py for data processing functions).

Directory Naming

  • Organization by Function: Directories should be organized by functionality (e.g., models/, controllers/, tests/).
  • Standard Directory Names: Keep directory names simple and standardized to make navigation intuitive.

Example Directory Structure:

project_root/
│
├── docs/
│   └── README.md
├── src/
│   ├── models/
│   ├── controllers/
│   ├── utils/
│   └── main.py
└── tests/
    ├── test_data_processing.py
    └── test_user_authentication.py

Workflow for Contributors

This workflow ensures consistent practices across contributors for setting up branches, working locally, and pushing changes.

Step 0: Clone the Repository

Clone the repository to your local environment if you haven’t already.

git clone git@github.com:MiadTechnologiesLCC/MidasTechnologies.git
cd MidasTechnologies

Step 1: Set Up Branch Tracking

Ensure you have the latest branches set up locally:

git fetch origin

Step 2: Check Out dev for New Work

Always base new work off the dev branch:

git checkout dev
git pull origin dev  # Ensure dev is up to date

Step 3: Create a New Branch Off dev

Create a new branch for your work based on the type of work you’re doing (feature, bugfix, docs, etc.). Follow the branch naming conventions.

git checkout -b feature/new-feature-name dev

Step 4: Make and Commit Changes

As you work, make regular commits with clear, descriptive messages following our commit message standards:

git add .
git commit -m "feat: add feature description"

Step 5: Push the Branch to GitHub

When ready, push your branch to GitHub:

git push -u origin feature/new-feature-name

Step 6: Create a Pull Request

  • Create PR: Go to GitHub and create a pull request (PR) from your feature branch into dev.
  • Review Request: Assign reviewers as necessary and respond to feedback.
  • Ensure Compliance: Confirm that the PR adheres to all required tests, checks, and naming conventions before approval and merging.

Common Mistakes to Avoid

  1. Directly Branching Off main: All branches should be created off dev unless given explicit permission from the repository manager.
  2. Inconsistent Naming: Stick to prefix conventions and lowercase names with hyphens to maintain clarity.
  3. Forgetting to Pull dev Updates: Always pull the latest changes from dev to avoid conflicts.
  4. Pushing to dev Without a PR: Changes should never be pushed directly to dev; submit all changes via a pull request.
  5. Improper File Naming: Follow naming standards strictly, with documentation files in Capitalized Case and code files in lowercase with underscores.

Code Review Policy

Table of Contents

  1. Code Review Workflow
  2. Working with Pull Requests
  3. Code Review Focus Areas
  4. Reviewer Responsibilities
  5. Contributor Responsibilities
  6. Final Approval and Merging Process
  7. Common Code Review Mistakes to Avoid
  8. Post-Review Responsibilities

Code Review Workflow

Opening a Pull Request

When creating a Pull Request (PR), adhere to the following guidelines to ensure a smooth and productive review process:

  1. Branch Source:

    • PRs must originate from designated branches, such as feature, bugfix, hotfix, or docs, following the Branch Naming Conventions.
    • PRs should generally target the dev branch, while only production-ready PRs may target the main branch. Merges to main are restricted to project maintainers to maintain code quality.

  2. Title & Description:

    • Use a clear and concise title for each PR.
    • Provide a thorough description, covering context, scope, and any relevant issues or implementation details.
    • Clearly indicate any special requirements for deployment, breaking changes, or additional dependencies.

  3. File Organization:

    • Follow the # file-path standards to ensure all new files and directories are structured for efficient navigation and ease of maintenance.

Review Assignment and Timeline

  • Assign PRs to experienced reviewers in relevant code areas. For complex changes, multiple reviewers may be required.
  • Use GitHub tags to notify reviewers, aiming for a 24–48 hour turnaround on PR reviews to support an efficient workflow.

Working with Pull Requests

Create a PR for Each Feature

  • Link the PR to any associated issues or tasks for traceability.
  • Request a review from team members knowledgeable about the relevant functionality.

Resolve All Conversations Before Merging

  • Address all reviewer feedback and mark conversations as resolved before final approval.
  • If substantial modifications are made in response to feedback, re-request a review to ensure consensus.

Merge Protocol

  • PRs into dev: These require at least one reviewer’s approval.
  • PRs from dev to main: Limited to the project maintainer, with thorough testing and final approval required to ensure the stability of main.

Code Review Focus Areas

Reviewers should concentrate on these critical areas to ensure quality, functionality, and maintainability across the codebase:

Code Quality and Consistency

  • Follow our Coding Standards for readability, maintainability, and consistency.
  • Maintain modularity and avoid redundancy, using existing functions or libraries where appropriate.
  • Confirm adherence to language-specific standards (e.g., PEP8 for Python).

Functionality and Completeness

  • Verify that the code performs as intended without regressions.
  • Ensure all specified use cases, including edge cases, are covered. Seek clarification from the contributor if requirements are ambiguous.

Testing and Coverage

  • Check for sufficient test coverage, ideally at least 85%, with a preference for automated tests.
  • Ensure all tests, including unit, integration, and end-to-end (E2E) tests, pass successfully.
  • Confirm compliance with the # file-path standards for consistency in test file organization.

Security and Performance

  • Assess for potential security vulnerabilities, especially in areas related to data handling, user authentication, or API calls.
  • Evaluate performance, suggesting improvements if any bottlenecks or inefficiencies are detected.

Documentation and Commenting

  • All public functions, classes, and methods should have clear docstrings, following our Documentation Standards.
  • Complex logic should be well-commented to explain non-standard approaches or optimizations.
  • Verify updates to user or developer documentation when relevant.

File Structure and Organization

  • Ensure new files and directories align with the # file-path standards to maintain logical structure.
  • Check that file organization is consistent with the established hierarchy, supporting ease of access and maintenance.

Reviewer Responsibilities

Reviewers are accountable for providing timely, constructive, and actionable feedback:

  • Timely Feedback: Complete PR reviews within 24–48 hours whenever possible.
  • Constructive Feedback: Offer specific, actionable suggestions for improvements, avoiding vague criticism.
  • Approval Process:
    • Only approve PRs if they meet quality standards and have no outstanding issues.
    • Request changes if additional work is needed or standards are not met.
    • Ensure compliance with the # file-path standards, naming conventions, and coding guidelines.
  • Professionalism: Maintain respect and clarity in all feedback, focusing on improvement.

Contributor Responsibilities

Contributors are responsible for ensuring their code is up to standard prior to submission:

  1. Self-Review: Conduct a thorough self-review, verifying clarity, standards compliance, and testing.
  2. Feedback Response: Address all reviewer comments and make necessary changes, re-requesting a review if major adjustments are made.
  3. Conversation Resolution: Mark all feedback conversations as resolved before requesting final approval.
  4. Commit Standards: Follow Commit Message Standards to keep commit messages informative, consistent, and concise.

Final Approval and Merging Process

Approval Requirements

  • PRs must have at least one reviewer’s approval, with additional reviewers for complex or high-risk changes.
  • Only project maintainers or designated personnel may approve and merge PRs into main.

Merging to Dev or Main

  • Merging into dev: Contributors may merge PRs after at least one review and approval.
  • Merging into main: Restricted to maintainers; requires extensive testing to confirm production readiness.

Final Checks Before Merging

  • Ensure all tests pass and the latest code changes are integrated into the PR.
  • Verify the # file-path standards are followed and the directory structure is organized.
  • Update the PR description with any final notes or additional context.

Common Code Review Mistakes to Avoid

  1. Skipping Self-Review: Self-review reduces back-and-forth and helps identify issues preemptively.
  2. Insufficient Test Coverage: Lack of comprehensive tests can lead to unexpected bugs. Aim to cover all use cases and edge scenarios.
  3. Premature Approval: Ensure understanding of the PR’s purpose and functionality before approving.
  4. File and Path Non-Compliance: Files should adhere to naming and path standards as detailed in # file-path standards.

Post-Review Responsibilities

Continuous Improvement

  • Identify opportunities for process improvement based on challenges encountered during the review.
  • Record valuable lessons, significant changes, or patterns in a shared knowledge base for future use.

Follow-up Tasks

  • Log any remaining issues or future improvements as GitHub issues for future sprints.
  • Update documentation when significant changes impact user guides, API references, or other project docs.

Retrospective and Feedback

  • Periodically evaluate the review process's effectiveness, gathering feedback to refine workflow, collaboration, and code quality practices.