Mining/docs/development/contributing.md

Contributing Guidelines

Thank you for considering contributing to the Mining Platform! This document provides guidelines for contributing to the project.

Code of Conduct

We expect all contributors to:

• Be respectful and inclusive
• Welcome newcomers and help them get started
• Accept constructive criticism gracefully
• Focus on what is best for the community
• Show empathy towards other community members

How to Contribute

Reporting Bugs

Before creating a bug report:

1. Check the existing issues to avoid duplicates
2. Collect relevant information (OS, Go version, logs, etc.)
3. Create a minimal reproducible example if possible

When creating a bug report, include:

• Title: Clear, descriptive summary
• Description: Detailed explanation of the issue
• Steps to Reproduce: Numbered list of steps
• Expected Behavior: What should happen
• Actual Behavior: What actually happens
• Environment:
  • OS and version
  • Go version
  • Mining Platform version
  • Miner software versions
• Logs: Relevant log output or error messages
• Screenshots: If applicable

Example:

### Bug: XMRig miner fails to start on Ubuntu 22.04

**Description:**
When attempting to start XMRig through the API, the miner process starts but immediately exits with code 1.

**Steps to Reproduce:**
1. Install Mining Platform v1.0.0
2. Install XMRig via `miner-ctrl install xmrig`
3. Start miner with: `POST /api/v1/mining/miners/xmrig`
4. Check miner status

**Expected Behavior:**
Miner should start and begin mining.

**Actual Behavior:**
Miner process exits immediately with error code 1.

**Environment:**
- OS: Ubuntu 22.04 LTS
- Go: 1.24.0
- Mining Platform: v1.0.0
- XMRig: 6.21.0

**Logs:**

[ERROR] Failed to start miner: process exited with code 1 [DEBUG] XMRig output: FAILED TO ALLOCATE MEMORY

Requesting Features

Feature requests are welcome! Before submitting:

1. Check if the feature already exists or is planned
2. Search existing feature requests
3. Consider if it fits the project scope

When requesting a feature, include:

• Use Case: Why is this feature needed?
• Description: What should the feature do?
• Alternatives: Have you considered other solutions?
• Examples: How would it work?

Submitting Pull Requests

1. Fork the Repository

   git clone https://github.com/YOUR_USERNAME/Mining.git
   cd Mining
   git remote add upstream https://github.com/Snider/Mining.git
   

2. Create a Branch

   git checkout -b feature/my-feature
   

   Branch naming convention:

   • feature/ - New features
   • fix/ - Bug fixes
   • docs/ - Documentation changes
   • refactor/ - Code refactoring
   • test/ - Test improvements

3. Make Your Changes

   • Write clean, readable code
   • Follow existing code style
   • Add tests for new functionality
   • Update documentation
   • Keep commits focused and atomic

4. Test Your Changes

   # Run Go tests
   make test
   make lint
   
   # Run frontend tests
   cd ui && npm test
   cd ui && npm run e2e
   

5. Commit Your Changes

   Follow Conventional Commits:

   type(scope): description
   
   [optional body]
   
   [optional footer]
   

   Types:

   • feat: New feature
   • fix: Bug fix
   • docs: Documentation
   • style: Formatting
   • refactor: Code restructuring
   • test: Tests
   • chore: Maintenance

   Examples:

   git commit -m "feat(api): Add profile management endpoints"
   git commit -m "fix(miner): Fix XMRig hashrate calculation"
   git commit -m "docs(readme): Update installation instructions"
   

6. Push to Your Fork

   git push origin feature/my-feature
   

7. Create a Pull Request

   • Go to the GitHub repository
   • Click "New Pull Request"
   • Select your branch
   • Fill in the PR template
   • Link related issues

Pull Request Guidelines

A good pull request:

• Focused: Addresses a single concern
• Tested: Includes tests for new code
• Documented: Updates relevant documentation
• Reviewed: Self-reviewed before submission
• Linked: References related issues

PR Template:

## Description
Brief description of what this PR does.

## Related Issues
Fixes #123
Relates to #456

## Changes
- Added X functionality
- Fixed Y bug
- Updated Z documentation

## Testing
- [ ] Go tests pass
- [ ] Frontend tests pass
- [ ] E2E tests pass
- [ ] Manual testing completed

## Checklist
- [ ] Code follows project style
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] Changelog updated
- [ ] Commits are atomic and well-described

Development Setup

See the Development Guide for detailed setup instructions.

Quick start:

# Clone
git clone https://github.com/YOUR_USERNAME/Mining.git
cd Mining

# Install dependencies
go mod download
cd ui && npm install

# Run tests
make test
cd ui && npm test

# Start dev environment
make dev

Coding Standards

Go Code Style

• Follow Effective Go
• Use gofmt for formatting
• Run golangci-lint before committing
• Write descriptive variable and function names
• Add comments for exported symbols
• Keep functions small and focused
• Handle errors explicitly

Good Example:

// GetMinerStats retrieves real-time statistics from a running miner.
// Returns an error if the miner is not running or stats cannot be fetched.
func (m *Manager) GetMinerStats(name string) (*PerformanceMetrics, error) {
    m.mu.RLock()
    miner, exists := m.miners[name]
    m.mu.RUnlock()

    if !exists {
        return nil, fmt.Errorf("miner %s not found", name)
    }

    stats, err := miner.GetStats()
    if err != nil {
        return nil, fmt.Errorf("failed to get stats: %w", err)
    }

    return stats, nil
}

TypeScript/Angular Code Style

• Follow Angular Style Guide
• Use TypeScript strict mode
• Prefer interfaces over types for objects
• Use RxJS operators properly
• Clean up subscriptions in ngOnDestroy
• Write unit tests for components and services

Good Example:

@Component({
  selector: 'app-miner-card',
  standalone: true,
  imports: [CommonModule],
  templateUrl: './miner-card.component.html',
  styleUrls: ['./miner-card.component.scss']
})
export class MinerCardComponent implements OnInit, OnDestroy {
  @Input() minerId!: string;
  miner$!: Observable<Miner>;

  private destroy$ = new Subject<void>();

  constructor(private minerService: MinerService) {}

  ngOnInit(): void {
    this.miner$ = this.minerService.getMiner(this.minerId).pipe(
      takeUntil(this.destroy$)
    );
  }

  ngOnDestroy(): void {
    this.destroy$.next();
    this.destroy$.complete();
  }
}

Documentation Standards

• Document all public APIs
• Include examples in documentation
• Keep documentation up-to-date with code
• Use clear, concise language
• Add diagrams for complex concepts

Testing Requirements

Required Tests

All PRs must include appropriate tests:

Go:

• Unit tests for new functions
• Integration tests for complex flows
• Table-driven tests where applicable
• Error case coverage

TypeScript/Angular:

• Unit tests for components and services
• E2E tests for user flows
• Test edge cases and error states

Running Tests

# Go tests
make test                    # All tests
go test -v ./pkg/mining/...  # Specific package
go test -run TestName        # Specific test

# Frontend tests
cd ui
npm test                     # Unit tests
npm run test:coverage        # With coverage
npm run e2e                  # E2E tests

Test Coverage

• Aim for >80% coverage for new code
• Don't decrease overall coverage
• Focus on critical paths

Check coverage:

make coverage    # Opens HTML report

Documentation

API Documentation

API changes require Swagger annotation updates:

// @Summary Get miner statistics
// @Description Returns real-time performance metrics for a running miner
// @Tags miners
// @Accept json
// @Produce json
// @Param name path string true "Miner name"
// @Success 200 {object} PerformanceMetrics
// @Failure 404 {object} ErrorResponse
// @Router /miners/{name}/stats [get]
func (s *Service) handleGetStats(c *gin.Context) {
    // Implementation
}

Generate docs:

make docs

User Documentation

Update relevant docs in docs/:

• Getting started guides
• API references
• User guides
• Architecture docs

Review Process

What to Expect

1. Automated Checks: CI runs tests and linters
2. Code Review: Maintainers review your code
3. Feedback: You may be asked to make changes
4. Approval: Once approved, PR will be merged

Responding to Feedback

• Be open to suggestions
• Ask questions if unclear
• Make requested changes promptly
• Explain your reasoning when necessary
• Keep discussions professional and constructive

Release Process

Releases are handled by maintainers:

1. Update CHANGELOG.md
2. Create a version tag
3. GitHub Actions builds and releases

Contributors don't need to worry about releases unless they're maintainers.

Getting Help

If you need help:

• Documentation: Check the docs/ folder first
• Issues: Search existing issues
• Discussions: Use GitHub Discussions for questions
• Discord: Join our community server (if available)

Recognition

Contributors are recognized in:

• CONTRIBUTORS.md file
• Release notes
• GitHub contributors page

Thank you for contributing to Mining Platform!

Quick Links

• Code of Conduct
• Development Guide
• Architecture Guide
• API Documentation
• Issue Tracker
• Discussions