GitHub Project Setup Guide

1. Repository Structure and Organization

Main Repositories

Standard Directory Structure

Each repository should maintain a consistent directory structure to help contributors navigate and understand the codebase:

project-root/
├── .github/                 # GitHub specific files
│   ├── ISSUE_TEMPLATE/      # Issue templates
│   ├── workflows/           # GitHub Actions workflows
│   └── PULL_REQUEST_TEMPLATE.md
├── docs/                    # Documentation files
│   ├── api/                 # API documentation
│   ├── contributing/        # Contribution guidelines
│   └── development/         # Development guides
├── src/                     # Source code
│   ├── assets/              # Static assets
│   ├── components/          # Reusable components
│   ├── pages/               # Main pages
│   ├── services/            # Service layers
│   └── utils/               # Utility functions
├── tests/                   # Test files
│   ├── unit/                # Unit tests
│   ├── integration/         # Integration tests
│   └── e2e/                 # End-to-end tests
├── .editorconfig            # Editor configuration
├── .gitignore               # Git ignore file
├── package.json             # Package dependencies
├── README.md                # Project overview
└── LICENSE                  # License information

Naming Conventions

2. Branching Strategy Guidelines

STEAM-Labz follows a simplified GitFlow branching strategy to maintain clean, organized repositories. This approach helps us manage releases and collaborate effectively across multiple contributors.

Main Branches

Supporting Branches

Workflow Visualization

Branch Lifecycle Guidelines

1. Create branches from the appropriate source - Feature branches from develop, hotfixes from main.
2. Keep branches focused - Each branch should address a single feature, bugfix, or specific change.
3. Update regularly - Pull changes from the source branch regularly to minimize merge conflicts.
4. Delete branches after merging - To keep the repository clean and manageable.
5. Never push directly to main or develop - Always use pull requests for changes to these branches.

3. Pull Request and Code Review Workflow

Pull requests (PRs) are the primary way we review and integrate code changes into our projects. They provide a platform for discussion, feedback, and improvement before code is merged.

Creating a Pull Request

git checkout develop
git pull
git checkout your-branch
git rebase develop

git push origin your-branch

PR Template

# Description

Please include a summary of the change and which issue is fixed. Include relevant 
motivation and context. List any dependencies that are required for this change.

Fixes # (issue)

## Type of change

Please delete options that are not relevant.

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] This change requires a documentation update

## How Has This Been Tested?

Please describe the tests that you ran to verify your changes. Provide instructions 
so we can reproduce. Please also list any relevant details for your test configuration.

## Checklist:

- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my own code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] Any dependent changes have been merged and published in downstream modules

Code Review Process

Merging Guidelines

1. All CI checks must pass - Including tests, linting, and build processes.
2. Minimum of one approval is required - Two or more for changes to critical components.
3. All review comments must be resolved - Ensure all feedback has been addressed.
4. Keep the commit history clean - Consider squashing commits if there are many small changes.
5. Update the PR description with final changes - If scope changed during review.

4. Issue Templates and Project Boards Setup

Well-structured issues and project boards help us track work, prioritize tasks, and maintain visibility across the project. STEAM-Labz uses GitHub Issues and Projects for managing all work items.

Issue Templates

We provide the following issue templates to ensure consistency and completeness:

Example Bug Report Template

---
name: Bug Report
about: Create a report to help us improve
title: '[BUG] '
labels: bug
assignees: ''
---

## Description
A clear and concise description of what the bug is.

## Steps To Reproduce
1. Go to '...'
2. Click on '...'
3. Scroll down to '...'
4. See error

## Expected Behavior
A clear and concise description of what you expected to happen.

## Screenshots
If applicable, add screenshots to help explain your problem.

## Environment
 - Device: [e.g. Desktop, iPhone X]
 - OS: [e.g. Windows 10, iOS 14]
 - Browser: [e.g. Chrome 89, Safari 14]
 - Version: [e.g. 1.2.0]

## Additional Context
Add any other context about the problem here.

Setting Up Project Boards

STEAM-Labz uses GitHub Projects to manage work. Each repository should have at least one project board with the following structure:

Project Board Automation

Set up the following automation rules in your GitHub Project:

Labels

Use the following standardized labels to categorize issues:

5. Documentation Standards

Good documentation is essential for any open-source project. STEAM-Labz follows a documentation-first approach, ensuring that all features, APIs, and processes are properly documented.

Documentation Types

Documentation Format

We use Markdown for all documentation files. For the main documentation site, we use Docusaurus which provides a clean, minimalist style similar to buspirate.com.

README.md Structure

Each repository should have a well-structured README.md with the following sections:

# Project Name

![STEAM-Labz Logo](logo-url.png)

Brief description of the project and its purpose within the STEAM-Labz ecosystem.

## Features

* Key feature 1
* Key feature 2
* Key feature 3

## Getting Started

### Prerequisites

List of software, tools, and dependencies required to run the project.

### Installation

Step-by-step installation instructions.

```bash
# Example installation commands
git clone https://github.com/STEAM-Labz/repository-name.git
cd repository-name
npm install
```

## Usage

Examples of how to use the project with code snippets.

## Contributing

Link to CONTRIBUTING.md with guidelines for contributing to the project.

## License

Information about the project's license.

## Contact

How to reach the maintainers.

Code Documentation Standards

For code documentation, we follow JSDoc style for JavaScript/TypeScript projects, and similar standards for other languages.

/**
 * Calculates the total score for a user based on their activities
 * 
 * @param {string} userId - The ID of the user
 * @param {Object} options - Configuration options
 * @param {boolean} options.includeInactive - Whether to include inactive activities
 * @param {number} options.timeframe - Timeframe in days to consider
 * @returns {Promise} The calculated score
 * @throws {Error} If the user doesn't exist or database connection fails
 * 
 * @example
 * // Get score for active activities in the last 30 days
 * const score = await calculateUserScore('user123', { 
 *   includeInactive: false,
 *   timeframe: 30
 * });
 */
async function calculateUserScore(userId, options = {}) {
    // Function implementation
}

Documentation Workflow

Docusaurus Setup

For our main documentation site (steam-labz-docs), we use Docusaurus to create a clean, minimalist style similar to buspirate.com.

npx @docusaurus/init@latest init steam-labz-docs classic

6. Step-by-Step Guide for New Contributors

We welcome contributions from everyone! This guide will help new contributors get started with the STEAM-Labz projects, regardless of their experience level.

Getting Started

# Fork the repository on GitHub
# Clone your fork
git clone https://github.com/your-username/repository-name.git
cd repository-name

# Add the original repository as upstream
git remote add upstream https://github.com/STEAM-Labz/repository-name.git

# Install dependencies
npm install  # or yarn install

# Create a new branch for your work
git checkout -b feature/your-feature-name

# Run tests
npm test

# Run linting
npm run lint

# Fix linting issues automatically (if available)
npm run lint:fix

# Stage your changes
git add .

# Commit with a descriptive message
git commit -m "Add feature: brief description of what you did"

# Push to your fork
git push origin feature/your-feature-name

# Make additional changes based on feedback
git add .
git commit -m "Address review feedback: description of changes"
git push origin feature/your-feature-name

Communication Channels

Join our community to get help and interact with other contributors:

Contribution Types

There are many ways to contribute to STEAM-Labz beyond just code:

7. Continuous Integration and Deployment Setup

STEAM-Labz uses GitHub Actions for continuous integration and deployment (CI/CD) to automate testing, build processes, and deployment to various environments.

CI/CD Workflow Overview

GitHub Actions Workflow Files

CI Workflow (.github/workflows/ci.yml)

name: CI

on:
  push:
    branches: [ '*' ]
  pull_request:
    branches: [ '*' ]

jobs:
  test:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Set up Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '16'
        cache: 'npm'
    
    - name: Install dependencies
      run: npm ci
    
    - name: Lint
      run: npm run lint
    
    - name: Run tests
      run: npm test
    
    - name: Build
      run: npm run build

Development Deployment (.github/workflows/deploy-dev.yml)

name: Deploy to Development

on:
  push:
    branches: [ develop ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Set up Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '16'
        cache: 'npm'
    
    - name: Install dependencies
      run: npm ci
    
    - name: Build
      run: npm run build
    
    - name: Deploy to Ubuntu Server
      uses: appleboy/scp-action@master
      with:
        host: ${{ secrets.DEV_SERVER_HOST }}
        username: ${{ secrets.DEV_SERVER_USERNAME }}
        key: ${{ secrets.DEV_SERVER_KEY }}
        source: "dist/"
        target: "/var/www/steam-labz.dev"
    
    - name: Restart service
      uses: appleboy/ssh-action@master
      with:
        host: ${{ secrets.DEV_SERVER_HOST }}
        username: ${{ secrets.DEV_SERVER_USERNAME }}
        key: ${{ secrets.DEV_SERVER_KEY }}
        script: |
          cd /var/www/steam-labz.dev
          pm2 restart steam-labz-dev

Production Deployment (.github/workflows/deploy-prod.yml)

name: Deploy to Production

on:
  push:
    branches: [ main ]
  release:
    types: [ published ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Set up Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '16'
        cache: 'npm'
    
    - name: Install dependencies
      run: npm ci
    
    - name: Build
      run: npm run build
    
    - name: Deploy to Ubuntu Server
      uses: appleboy/scp-action@master
      with:
        host: ${{ secrets.PROD_SERVER_HOST }}
        username: ${{ secrets.PROD_SERVER_USERNAME }}
        key: ${{ secrets.PROD_SERVER_KEY }}
        source: "dist/"
        target: "/var/www/steam-labz.com"
    
    - name: Restart service
      uses: appleboy/ssh-action@master
      with:
        host: ${{ secrets.PROD_SERVER_HOST }}
        username: ${{ secrets.PROD_SERVER_USERNAME }}
        key: ${{ secrets.PROD_SERVER_KEY }}
        script: |
          cd /var/www/steam-labz.com
          pm2 restart steam-labz

    - name: Run smoke tests
      run: npm run test:smoke

Setting Up GitHub Secrets

For the deployment workflows to work, you need to set up the following secrets in your GitHub repository:

1. DEV_SERVER_HOST - The hostname or IP of your development server
2. DEV_SERVER_USERNAME - SSH username for the development server
3. DEV_SERVER_KEY - SSH private key for the development server
4. PROD_SERVER_HOST - The hostname or IP of your production server
5. PROD_SERVER_USERNAME - SSH username for the production server
6. PROD_SERVER_KEY - SSH private key for the production server

Cloudflare Integration

STEAM-Labz uses Cloudflare for CDN, security, and streaming services. Here's how to integrate Cloudflare with our CI/CD pipeline:

- name: Purge Cloudflare cache
  run: |
    curl -X POST "https://api.cloudflare.com/client/v4/zones/${{ secrets.CLOUDFLARE_ZONE_ID }}/purge_cache" \
      -H "Authorization: Bearer ${{ secrets.CLOUDFLARE_API_TOKEN }}" \
      -H "Content-Type: application/json" \
      --data '{"purge_everything":true}'

8. Security Best Practices

Security is a critical aspect of any project. STEAM-Labz follows industry best practices to ensure the security of our codebase, infrastructure, and user data.

Code Security

Secret Management

Never store secrets (API keys, passwords, tokens) in the codebase. Instead:

1. Use environment variables for configuration and secrets
2. Store secrets in GitHub Secrets for CI/CD workflows
3. Use a secrets manager like HashiCorp Vault for production environments
4. Rotate secrets regularly and when team members leave
5. Use .env files locally but exclude them from version control with .gitignore

Example .gitignore entries for secrets

# Environment variables
.env
.env.local
.env.development
.env.test
.env.production

# Private keys
*.pem
*.key

# Configuration files with secrets
config.json
secrets.json

Authentication and Authorization

Infrastructure Security

Security Testing

Integrate security testing into your CI/CD pipeline:

- name: Run CodeQL analysis
  uses: github/codeql-action/analyze@v2

- name: Check for vulnerabilities
  run: npm audit

Incident Response

Have a plan for handling security incidents:

1. Create an incident response plan that outlines steps to take when a security issue is identified
2. Establish a responsible disclosure policy for reporting security vulnerabilities
3. Document lessons learned from any security incidents to prevent similar issues in the future
4. Have a communication plan for notifying affected users if necessary