# Contribution Guidelines

## Development Workflow

This repository uses a protected main branch with automated testing to ensure code quality.

### ✅ Required Workflow:

1. **Create feature branches** from main:
   ```bash
   git checkout -b feature/your-feature-name
   ```

2. **Make your changes** and commit them:
   ```bash
   git add .
   git commit -m "Add your feature description"
   ```

3. **Push your branch** to remote:
   ```bash
   git push origin feature/your-feature-name
   ```

4. **Create a Pull Request** from GitHub UI:
   - Target branch: `main`
   - Title: Clear description of changes
   - Description: Purpose and testing notes

5. **Wait for integration tests** to complete (automatic)
6. **Get code review approval** from at least one team member
7. **Merge** only when all tests pass

### 🚫 Prohibited Actions:

- **Direct pushes to main branch are blocked**
- **Merges with failing tests are prevented**
- **Bypassing protection rules is not allowed**

## Branch Protection Rules

The main branch is protected with these automated rules:

### ✅ Automated Enforcement:
- ✅ **Direct pushes blocked**: GitHub Actions workflow prevents pushes to main
- ✅ **Integration tests required**: All PRs must pass tests before merging
- ✅ **Pull Requests required**: Basic branch protection enforces PR workflow
- ✅ **Status checks required**: Tests must pass before merge is allowed

### 👥 Team Responsibilities:
- 🔍 **Code Review**: At least one approval required before merging
- 🧪 **Test Quality**: Ensure all tests pass before requesting review
- 📝 **Documentation**: Update relevant docs with your changes
- 🎯 **Small PRs**: Keep Pull Requests focused and reviewable

## Setting Up Branch Protection

To configure these rules in your repository:

1. Go to: **Repository Settings → Branches**
2. Click **"Add branch protection rule"**
3. Enter branch name pattern: `main`
4. Enable these options:
   - ✅ **Require a pull request before merging**
   - ✅ **Require status checks to pass before merging**
   - ✅ Select: `Integration Tests` workflow
   - ✅ **Do not allow bypassing the above settings**

## Local Development Setup

### Rust + React Project Structure

```
andromeda/
├── backend/          # Rust backend (if applicable)
│   ├── Cargo.toml
│   └── src/
├── frontend/         # React frontend (if applicable)
│   ├── package.json
│   └── src/
├── .github/
│   └── workflows/
├── CONTRIBUTING.md
└── README.md
```

### Rust Development

```bash
# Navigate to Rust backend (if separate directory)
cd backend

# Check Rust formatting
cargo fmt --all --check

# Run Rust linter
cargo clippy -- -D warnings

# Run Rust tests
cargo test

# Build Rust project
cargo build --release
```

### React Development

```bash
# Navigate to React frontend (if separate directory)
cd frontend

# Install dependencies
npm install

# Run React tests
npm test

# Run React app in development mode
npm start

# Build React app for production
npm run build

# Run linting (optional)
npm run lint
```

### Full Workflow Example

```bash
# Clone the repository
git clone https://github.com/your-repo/andromeda.git
cd andromeda

# Set up both Rust and React environments
cd backend && cargo build
cd ../frontend && npm install

# Run all tests locally before pushing
cd backend && cargo test
cd ../frontend && npm test

# Create and switch to feature branch
git checkout -b feature/your-feature

# Make changes, commit, and push
git add .
git commit -m "Add feature description"
git push origin feature/your-feature
```

## How It Works

### ✅ Successful Pull Request Flow:
```
Feature Branch → Push → Create PR → Tests Run → Tests Pass → Review → Approve → Merge
```

### ❌ Blocked Direct Push:
```
Main Branch Push → GitHub Actions → Workflow Fails → Push Rejected
```

### ❌ Failing Tests:
```
Create PR → Tests Run → Tests Fail → Merge Button Disabled → Fix Required
```

## Troubleshooting

**Issue: "Push to main was rejected"**
- Solution: Create a feature branch and use Pull Request workflow

**Issue: "Tests are failing on my PR"**
- Solution: Run tests locally (`npm test`), fix issues, push updates

**Issue: "Merge button is disabled"**
- Solution: Check test results and fix any failures

## Best Practices

- **Small, focused PRs**: Easier to review and test
- **Descriptive commits**: Clear, concise commit messages
- **Test locally first**: Run `npm test` before pushing
- **Update documentation**: Keep docs in sync with code changes
- **Respond to reviews**: Address feedback promptly

## Contact

For questions about the contribution process:
- Open an issue with your question
- Ask in team chat channels
- Review existing Pull Requests for examples

## Local Development

```bash
# Create and switch to a new feature branch
git checkout -b feature/your-feature-name

# Make your changes and commit
git add .
git commit -m "Add your feature description"

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

# Create Pull Request from GitHub UI
```