telecom-platform/CONTRIBUTING.md

Contributing to TaaS Platform

Thank you for your interest in contributing to the TaaS Platform! This document provides guidelines for contributing to the project.

Table of Contents

• Getting Started
• Project Structure
• Development Workflow
• Code Style
• Testing
• Commit Message Format
• Pull Request Process
• CI/CD
• Release Process
• Reporting Issues
• License

Getting Started

Prerequisites

• Go 1.26+: Download
• Rust 1.94+: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
• Node.js 22+: Download
• pnpm: npm install -g pnpm
• Docker: Install
• PostgreSQL 15+: Install
• Redis: Install
• Kubernetes: Install (for production deployment)
• Helm 3+: Install (for production deployment)
• MongoDB 7.0+: Install (required for free5GC only)

Setup

1. Fork the repository
2. Clone your fork:

   git clone https://github.com/nutcas3/telecom-platform.git
   cd telecom-platform
   

3. Install dependencies:

   make install-deps
   

4. Set up databases:

   make db-setup
   make db-migrate
   

5. Build all components:

   make all
   

Project Structure

telecom-platform/
├── apps/
│   ├── api-server/          # Go BSS API server
│   ├── carrier-connector/   # Go ES2+ carrier integration
│   ├── charging-engine/     # Rust real-time charging
│   ├── packet-gateway/      # Rust eBPF packet processing
│   ├── cli/                 # Go CLI tool
│   └── web-dashboard/       # Next.js management UI
├── sdk/
│   └── typescript/          # TypeScript SDK
├── deployments/
│   ├── docker/              # Dockerfiles
│   ├── kubernetes/          # K8s manifests
│   ├── helm/                # Helm charts
│   └── free5gc/             # 5G core network config
├── monitoring/             # Prometheus/Grafana configs
└── scripts/                # Setup and utility scripts

Development Workflow

1. Create a feature branch:

   git checkout -b feature/your-feature-name
   

2. Make your changes:

   • Write clear, documented code
   • Follow language-specific style guides
   • Add tests for new functionality
   • Update documentation as needed

3. Run linters:

   make lint
   

4. Run tests:

   make test
   

5. Format code:

   make fmt
   

6. Commit your changes:

   git add .
   git commit -m "feat: add new feature"
   

7. Push to your fork:

   git push origin feature/your-feature-name
   

8. Create a Pull Request

Code Style

Go

• Follow Effective Go
• Use gofmt for formatting: make fmt-go
• Run golangci-lint before committing: make lint-go
• Use descriptive variable and function names
• Add godoc comments for exported functions
• Handle errors explicitly, don't ignore them

Rust

• Follow Rust API Guidelines
• Use cargo fmt for formatting: cargo fmt
• Run cargo clippy before committing: make lint-rust
• Use Result<T, E> for error handling
• Prefer unwrap() only in tests
• Document unsafe blocks with safety comments

TypeScript

• Follow Airbnb Style Guide
• Use Prettier for formatting: make lint-ui
• Use ESLint for linting
• Use TypeScript strict mode
• Prefer functional programming patterns
• Add JSDoc comments for public APIs

Testing

Testing Strategy

• Unit Tests: Test individual functions and methods in isolation
• Integration Tests: Test service interactions with real dependencies
• End-to-End Tests: Test complete workflows across services
• Race Detection: Use -race flag for Go tests to detect data races

Running Tests

# Run all tests
make test

# Run Go tests with race detection
make test-go

# Run Rust tests in release mode
make test-rust-release

# Run TypeScript tests
pnpm -r test

Test Coverage

• Aim for >80% code coverage on new code
• Run coverage reports before submitting PRs
• Add tests for bug fixes to prevent regressions

Commit Message Format

We use Conventional Commits:

<type>(<scope>): <subject>

<body>

<footer>

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting)
• refactor: Code refactoring
• test: Adding or updating tests
• chore: Maintenance tasks
• perf: Performance improvements
• ci: CI/CD changes

Scopes:

• api: API server changes
• charging: Charging engine changes
• gateway: Packet gateway changes
• connector: Carrier connector changes
• cli: CLI tool changes
• dashboard: Web dashboard changes
• sdk: TypeScript SDK changes
• infra: Infrastructure changes
• docs: Documentation changes

Examples:

feat(api): add eSIM deletion endpoint
fix(charging): correct credit deduction logic
docs: update deployment guide
perf(gateway): optimize eBPF packet processing
ci: add race detection to tests

Pull Request Process

1. Update documentation if needed
2. Add tests for your changes
3. Ensure all tests pass: make test
4. Run linters: make lint
5. Format code: make fmt
6. Update CHANGELOG.md with your changes
7. Request review from maintainers
8. Address review feedback promptly
9. Wait for approval and merge

PR Checklist

• Code follows project style guidelines
• Tests added/updated and passing
• Documentation updated
• CHANGELOG.md updated
• No merge conflicts
• Commit messages follow conventional commits

CI/CD

GitHub Actions

The project uses GitHub Actions for:

• Linting: golangci-lint, clippy, ESLint
• Testing: Go tests with race detection, Rust tests, TypeScript tests
• Building: Docker images for all services
• Security: Trivy vulnerability scanning

Branch Protection

• main and develop branches are protected
• PRs require at least one approval
• CI must pass before merging
• No direct pushes to protected branches

Release Process

1. Update version numbers in relevant files
2. Update CHANGELOG.md with release notes
3. Create release branch: git checkout -b release/v1.0.0
4. Run full test suite: make test
5. Build Docker images: make docker-build
6. Tag release: git tag -a v1.0.0 -m "Release v1.0.0"
7. Push tag: git push origin v1.0.0
8. Create GitHub release with notes
9. Deploy to production: make k8s-deploy-helm

Reporting Issues

When reporting bugs or requesting features:

1. Use GitHub Issues with appropriate templates
2. Provide clear description of the problem
3. Include reproduction steps
4. Add relevant logs or screenshots
5. Specify environment details:
   • OS and version
   • Go/Rust/Node.js versions
   • Database versions
   • Kubernetes version (if applicable)

Code Review

We review all contributions. Expect:

• Feedback on code quality and best practices
• Suggestions for improvements and optimizations
• Questions about implementation decisions
• Requests for tests or documentation
• Security considerations for sensitive code

Security

• Report security vulnerabilities privately to maintainers
• Never commit secrets, API keys, or passwords
• Use Vault for secret management in production
• Follow OWASP guidelines for security best practices

License

By contributing, you agree that your contributions will be licensed under the MIT License.