andwati/telecom-platform
1
0
Fork 0
mirror of https://github.com/andwati/telecom-platform.git synced 2026-10-18 02:52:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Expand CONTRIBUTING.md with comprehensive development guidelines and workflow details

Browse Source 
- Add table of contents for easier navigation
- Add Prerequisites section with required tools and versions (Go 1.26+, Rust 1.94+, Node.js 22+, etc.)
- Add detailed Setup section with database setup and build instructions
- Add Project Structure section documenting repository layout
- Expand Development Workflow with linting, formatting, and testing steps
- Add detailed Code Style sections for Go, Rust, and Type
This commit is contained in:
nutcas3
2026-04-25 23:12:40 +03:00
parent eb4297d679
commit c3f81402a0
1 changed files with 210 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+210 -35
View File
@@ -2,20 +2,79 @@
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](#getting-started)
- [Project Structure](#project-structure)
- [Development Workflow](#development-workflow)
- [Code Style](#code-style)
- [Testing](#testing)
- [Commit Message Format](#commit-message-format)
- [Pull Request Process](#pull-request-process)
- [CI/CD](#cicd)
- [Release Process](#release-process)
- [Reporting Issues](#reporting-issues)
- [License](#license)
## Getting Started
### Prerequisites
- **Go 1.26+**: [Download](https://go.dev/dl/)
- **Rust 1.94+**: `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
- **Node.js 22+**: [Download](https://nodejs.org/)
- **pnpm**: `npm install -g pnpm`
- **Docker**: [Install](https://docs.docker.com/get-docker/)
- **PostgreSQL 15+**: [Install](https://www.postgresql.org/download/)
- **Redis**: [Install](https://redis.io/download)
- **Kubernetes**: [Install](https://kubernetes.io/docs/tasks/tools/) (for production deployment)
- **Helm 3+**: [Install](https://helm.sh/docs/intro/install/) (for production deployment)
- **MongoDB 7.0+**: [Install](https://www.mongodb.com/docs/manual/installation/) (required for free5GC only)
### Setup
1. **Fork the repository**
2. **Clone your fork:**
```bash
git clone https://github.com/nutcas3/telecom-platform.git
cd telecom-platform
```
3. **Set up development environment:**
3. **Install dependencies:**
```bash
make install-deps
```
4. **Set up databases:**
```bash
make db-setup
make db-migrate
```
5. **Build all components:**
```bash
./scripts/dev-setup.sh
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:**
@@ -27,41 +86,95 @@ Thank you for your interest in contributing to the TaaS Platform! This document
- Write clear, documented code
- Follow language-specific style guides
- Add tests for new functionality
- Update documentation as needed
3. **Run tests:**
3. **Run linters:**
```bash
make lint
```
4. **Run tests:**
```bash
make test
```
4. **Commit your changes:**
5. **Format code:**
```bash
make fmt
```
6. **Commit your changes:**
```bash
git add .
git commit -m "feat: add new feature"
```
5. **Push to your fork:**
7. **Push to your fork:**
```bash
git push origin feature/your-feature-name
```
6. **Create a Pull Request**
8. **Create a Pull Request**
## Code Style
### Go
- Follow [Effective Go](https://go.dev/doc/effective_go)
- Use `gofmt` for formatting
- Run `golangci-lint` before committing
- 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](https://rust-lang.github.io/api-guidelines/)
- Use `cargo fmt` for formatting
- Run `cargo clippy` before committing
- 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](https://github.com/airbnb/javascript)
- Use Prettier for formatting
- 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
```bash
# 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
@@ -83,46 +196,108 @@ We use [Conventional Commits](https://www.conventionalcommits.org/):
- `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
```
## Testing
- Write unit tests for all new code
- Ensure existing tests pass
- Add integration tests for API endpoints
- Test edge cases and error conditions
## Pull Request Process
1. Update documentation if needed
2. Add tests for your changes
3. Ensure all tests pass
4. Update CHANGELOG.md
5. Request review from maintainers
6. Address review feedback
7. Wait for approval and merge
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
- Suggestions for improvements
- Questions about implementation
- Requests for tests or documentation
- **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
## Reporting Issues
## Security
- Use GitHub Issues
- Provide clear description
- Include reproduction steps
- Add relevant logs or screenshots
- Specify environment details
- 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