GitHub Guide

📋 Table of Contents

1. GitHub Repo Structure

2. Branching Strategy

3. Committing Code

4. Pull Requests

5. Code Review Process

6. Deployment

7. Best Practices

8. Useful Git Commands

📁 GitHub Repo Structure

For our web development and blockchain projects, we typically use the following structure:

project-root/
├── src/
│   ├── components/
│   ├── pages/
│   ├── styles/
│   ├── utils/
│   └── App.js
├── public/
├── contracts/ (for blockchain projects)
│   ├── interfaces/
│   └── test/
├── scripts/
├── config/
├── docs/
├── tests/
├── .gitignore
├── package.json
├── README.md
└── LICENSE

• src/: Contains the main source code for the web application

• public/: Stores static assets and the main HTML file

• contracts/: (For blockchain projects) Stores smart contract code and tests

• scripts/: Contains build and deployment scripts

• config/: Holds configuration files

• docs/: Project documentation

• tests/: Unit and integration tests

🌿 Branching Strategy

Format:

<type>/<TICKET_NUMBER>-<short-description>

Components:

• <type>:

  • feature: New features or enhancements

  • bugfix: Bug fixes

  • hotfix: Urgent fixes for production

  • chore: Routine tasks and maintenance

• <TICKET_NUMBER>:

  • The identifier from our project management tool (e.g., TICKET-1234)

• <short-description>:

  • A brief, kebab-case description of the work (e.g., add-user-authentication)

🌟 Examples

• feature/TICKET-1234-add-user-authentication

• bugfix/TICKET-5678-fix-login-error

• hotfix/TICKET-9012-patch-security-vulnerability

• chore/TICKET-3456-update-dependencies

🔨 Creating a New Branch

1. Identify the ticket number from our project management tool

2. Determine the branch type based on the task

3. Create the branch using the following format:

   git checkout -b feature/TICKET-1234-add-user-authentication

💻 Committing Code

We use the following structure for commit messages: Ticket Number | Name | Description

Examples:

• TICKET-1234 | JohnDoe | Add user authentication feature

• BUG-1234 | JohnDoe | Fix login issue

• TASK-1234 | JohnDoe | Update API endpoint for retrieving user details

Note: You will get the ticket number from the Hubstaff Kanban board.

🔀 Pull Requests

When your work is ready for review, create a pull request (PR) following these guidelines:

1. Title: Use the format [TICKET-NUMBER] Brief description of changes Example: [TICKET-1234] Implement user authentication feature

2. Description: Include the following sections:

   • Summary of changes

   • How to test

   • Screenshots (if applicable)

   • Any additional notes or concerns

3. Reviewers: Assign at least one team member to review your PR

4. Labels: Add appropriate labels (e.g., 'bug', 'feature', 'documentation')

5. Link to Ticket: Include a link to the related ticket in the PR description

6. Branch: Push your feature branch and create a PR to merge into main

7. Checks: Ensure all checks pass before merging

👀 Code Review Process

1. Reviewers should provide constructive feedback within 24 hours

2. Address all comments and make necessary changes

3. Once approved, merge the PR using the squash and merge strategy

🚢 Deployment

1. Staging: All merged PRs are automatically deployed to the staging environment

2. Production: After thorough testing on staging, create a release PR to merge develop into main

✅ Best Practices

1. Keep commits atomic: Each commit should represent a single logical change

2. Write clear commit messages: Follow the commit message structure outlined above

3. Regular updates: Pull from the main branch frequently to stay up-to-date

4. Code style: Adhere to the team's agreed-upon coding standards and use linters

5. Documentation: Update relevant documentation as part of your changes

🛠️ Useful Git Commands

1. Create a new branch:

   git checkout -b <type>/<TICKET_NUMBER>-<short-description>

2. Push to a remote branch:

   git push origin <branch-name>

3. Pull the latest changes:

   git pull origin main

4. Merge a branch:

   git merge <branch-name>

5. Delete a branch:

   git branch -d <branch-name>

6. Create a new PR:

   git pull origin main

7. Stash changes:

   git stash

8. Apply stashed changes:

   git stash pop

9. View commit history:

   git log

10. Undo last commit (keeping changes):

    git reset HEAD~1