# GitHub Repository Setup Instructions

This document provides step-by-step instructions for setting up the RedFlag GitHub repository.

## Prerequisites

- Git installed locally
- GitHub account with appropriate permissions
- SSH key configured with GitHub (recommended)

## Initial Repository Setup

### 1. Initialize Git Repository

```bash
# Initialize the repository
git init

# Add all files
git add .

# Make initial commit
git commit -m "Initial commit - RedFlag update management platform

🚩 RedFlag - Self-hosted update management platform

✅ Features:
- Go server backend with PostgreSQL
- Linux agent with APT + Docker scanning
- React web dashboard with TypeScript
- REST API with JWT authentication
- Local CLI tools for agents
- Update discovery and approval workflow

🚧 Status: Alpha software - in active development
📖 See README.md for setup instructions and current limitations."

# Set main branch
git branch -M main
```

### 2. Connect to GitHub Repository

```bash
# Add remote origin (replace with your repository URL)
git remote add origin git@github.com:Fimeg/RedFlag.git

# Push to GitHub
git push -u origin main
```

## Repository Configuration

### 1. Create GitHub Repository

1. Go to GitHub.com and create a new repository named "RedFlag"
2. Choose "Public" (AGPLv3 requires public source)
3. Don't initialize with README, .gitignore, or license (we have these)
4. Copy the repository URL (SSH recommended)

### 2. Repository Settings

After pushing, configure these repository settings:

#### General Settings
- **Description**: "🚩 Self-hosted, cross-platform update management platform - 'From each according to their updates, to each according to their needs'"
- **Website**: `https://redflag.dev` (when available)
- **Topics**: `update-management`, `self-hosted`, `devops`, `linux`, `docker`, `cross-platform`, `agplv3`, `homelab`
- **Visibility**: Public

#### Branch Protection
- Protect `main` branch
- Require pull request reviews (at least 1)
- Require status checks to pass before merging (when CI/CD is added)

#### Security & Analysis
- Enable **Dependabot alerts**
- Enable **Dependabot security updates**
- Enable **Code scanning** (when GitHub Advanced Security is available)

#### Issues
- Enable issues for bug reports and feature requests
- Create issue templates:
  - Bug Report
  - Feature Request
  - Security Issue

### 3. Create Issue Templates

Create `.github/ISSUE_TEMPLATE/` directory with these templates:

#### bug_report.md
```markdown
---
name: Bug report
about: Create a report to help us improve
title: '[BUG] '
labels: bug
assignees: ''
---

**Describe the bug**
A clear and concise description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior:
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:**
 - OS: [e.g. Ubuntu 22.04]
 - RedFlag version: [e.g. Session 4]
 - Deployment method: [e.g. Docker, source]

**Additional context**
Add any other context about the problem here.
```

#### feature_request.md
```markdown
---
name: Feature request
about: Suggest an idea for this project
title: '[FEATURE] '
labels: enhancement
assignees: ''
---

**Is your feature request related to a problem? Please describe.**
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

**Describe the solution you'd like**
A clear and concise description of what you want to happen.

**Describe alternatives you've considered**
A clear and concise description of any alternative solutions or features you've considered.

**Additional context**
Add any other context or screenshots about the feature request here.
```

### 4. Create Pull Request Template

Create `.github/pull_request_template.md`:

```markdown
## Description
<!-- Describe your changes in detail -->

## Type of Change
- [ ] 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)
- [ ] Documentation update

## Testing
- [ ] I have tested the changes locally
- [ ] I have added appropriate tests
- [ ] All tests pass

## Checklist
- [ ] My code follows the project's coding standards
- [ ] I have performed a self-review of my own code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have updated the documentation accordingly
- [ ] 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

## Security
- [ ] I have reviewed the security implications of my changes
- [ ] I have considered potential attack vectors
- [ ] I have validated input and sanitized data where appropriate

## Additional Notes
<!-- Any additional information that might be helpful for reviewers -->
```

### 5. Create Development Guidelines

Create `CONTRIBUTING.md`:

```markdown
# Contributing to RedFlag

Thank you for your interest in contributing to RedFlag!

## Development Status

⚠️ **RedFlag is currently in alpha development**
This means:
- Breaking changes are expected
- APIs may change without notice
- Documentation may be incomplete
- Some features are not yet implemented

## Getting Started

### Prerequisites
- Go 1.25+
- Node.js 18+
- Docker & Docker Compose
- PostgreSQL 16+

### Development Setup
1. Clone the repository
2. Read `README.md` for setup instructions
3. Follow the development workflow below

## Development Workflow

### 1. Create a Branch
```bash
git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix
```

### 2. Make Changes
- Follow existing code style and patterns
- Add tests for new functionality
- Update documentation as needed

### 3. Test Your Changes
```bash
# Run tests
make test

# Test locally
make dev
```

### 4. Submit a Pull Request
- Create a descriptive pull request
- Link to relevant issues
- Wait for code review

## Code Style

### Go
- Follow standard Go formatting
- Use `gofmt` and `goimports`
- Write clear, commented code

### TypeScript/React
- Follow existing patterns
- Use TypeScript strictly
- Write component tests

### Documentation
- Update README.md for user-facing changes
- Update inline code comments
- Add technical documentation as needed

## Security Considerations

RedFlag manages system updates, so security is critical:

1. **Never commit secrets, API keys, or passwords**
2. **Validate all input data**
3. **Use parameterized queries**
4. **Review code for security vulnerabilities**
5. **Test for common attack vectors**

## Areas That Need Help

- **Windows agent** - Windows Update API integration
- **Package managers** - snap, flatpak, chocolatey, brew
- **Web dashboard** - UI improvements, new features
- **Documentation** - Installation guides, troubleshooting
- **Testing** - Unit tests, integration tests
- **Security** - Code review, vulnerability testing

## Reporting Issues

- Use GitHub Issues for bug reports and feature requests
- Provide detailed reproduction steps
- Include environment information
- Follow security procedures for security issues

## License

By contributing to RedFlag, you agree that your contributions will be licensed under the AGPLv3 license.

## Questions?

- Create an issue for questions
- Check existing documentation
- Review existing issues and discussions

Thank you for contributing! 🚩
```

## Post-Setup Validation

### 1. Verify Repository
- [ ] Repository is public
- [ ] README.md displays correctly
- [ ] All files are present
- [ ] .gitignore is working (no sensitive files committed)
- [ ] License is set to AGPLv3

### 2. Test Workflow
- [ ] Can create issues
- [ ] Can create pull requests
- [ ] Branch protection is active
- [ ] Dependabot is enabled

### 3. Documentation
- [ ] README.md is up to date
- [ ] CONTRIBUTING.md exists
- [ ] Issue templates are working
- [ ] PR template is working

## Next Steps

After repository setup:

1. **Create initial issues** for known bugs and feature requests
2. **Set up project board** for roadmap tracking
3. **Enable Discussions** for community questions
4. **Create releases** when ready for alpha testing
5. **Set up CI/CD** for automated testing

## Security Notes

- 🔐 Never commit secrets or API keys
- 🔐 Use environment variables for configuration
- 🔐 Review all code for security issues
- 🔐 Enable security features in GitHub
- 🔐 Monitor for vulnerabilities with Dependabot

---

*Repository setup completed! RedFlag is now ready for collaborative development.* 🚩