Skip to main content

Contributing to NetTraceX

Thank you for your interest in contributing to NetTraceX! This guide will help you get started with contributing to the project.

Getting Started​

Prerequisites​

  • Go 1.21 or later
  • Git
  • Make (for Unix/Linux/macOS) or PowerShell (for Windows)
  • A terminal emulator

Development Setup​

  1. Fork the repository

    # Fork the repository on GitHub, then clone your fork
    git clone https://github.com/your-username/nettracex-tui.git
    cd nettracex

  2. Set up the development environment

    # Add upstream remote
    git remote add upstream https://github.com/nettracex/nettracex-tui.git

    # Install dependencies
    go mod download
    go mod tidy

  3. Build the project

    # Unix/Linux/macOS
    make build

    # Windows
    go build -o bin/nettracex.exe ./cmd/nettracex

  4. Run tests

    # Run all tests
    go test ./...

    # Run tests with coverage
    go test -coverprofile=coverage.out ./...
    go tool cover -html=coverage.out

Development Workflow​

1. Create a Feature Branch​

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

# Or for bug fixes
git checkout -b fix/your-bug-description

2. Make Your Changes​

  • Follow the existing code style and patterns
  • Write tests for new functionality
  • Update documentation as needed
  • Ensure all tests pass

3. Test Your Changes​

# Run the full test suite
go test ./...

# Run specific tests
go test ./internal/domain -v
go test ./internal/tools/ping -v

# Run with race detection
go test -race ./...

# Run with coverage
go test -cover ./...

4. Commit Your Changes​

# Stage your changes
git add .

# Commit with a descriptive message
git commit -m "feat: add new diagnostic tool for network latency"

5. Push and Create a Pull Request​

# Push your branch
git push origin feature/your-feature-name

Then create a pull request on GitHub.

Code Style and Standards​

Go Code Style​

  • Follow the Effective Go guidelines
  • Use gofmt to format your code
  • Use golint to check for style issues
  • Use go vet to check for potential issues
# Format code
go fmt ./...

# Check for issues
go vet ./...

# Lint code (if golangci-lint is installed)
golangci-lint run

Commit Message Convention​

We follow the Conventional Commits specification:

  • feat: - New features
  • fix: - Bug fixes
  • docs: - Documentation changes
  • style: - Code style changes
  • refactor: - Code refactoring
  • test: - Test changes
  • chore: - Maintenance tasks

Examples:

feat: add SSL certificate validation tool
fix: resolve timeout issue in ping tool
docs: update installation guide
test: add unit tests for DNS tool

Code Organization​

Follow the clean architecture principles:

internal/
├── domain/           # Core business logic
│   ├── interfaces.go
│   ├── types.go
│   └── *_test.go
├── application/      # Use cases
│   ├── services/
│   └── handlers/
├── infrastructure/   # External dependencies
│   ├── network/
│   └── storage/
└── presentation/     # UI components
    ├── tui/
    └── cli/

Testing Guidelines​

Unit Tests​

  • Write tests for all public functions
  • Aim for high test coverage (80%+)
  • Use table-driven tests for multiple scenarios
  • Mock external dependencies

Example:

func TestPingTool_Execute(t *testing.T) {
    tests := []struct {
        name    string
        params  PingParameters
        want    PingResult
        wantErr bool
    }{
        {
            name: "successful ping",
            params: PingParameters{
                Host:   "8.8.8.8",
                Count:  4,
            },
            want: PingResult{
                Host: "8.8.8.8",
                // ... expected result
            },
            wantErr: false,
        },
        // ... more test cases
    }
    
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            tool := &PingTool{}
            got, err := tool.Execute(context.Background(), tt.params)
            
            if (err != nil) != tt.wantErr {
                t.Errorf("Execute() error = %v, wantErr %v", err, tt.wantErr)
                return
            }
            
            if !reflect.DeepEqual(got, tt.want) {
                t.Errorf("Execute() = %v, want %v", got, tt.want)
            }
        })
    }
}

Integration Tests​

  • Test the complete workflow
  • Use real network calls (with timeouts)
  • Test error handling and edge cases

Performance Tests​

  • Benchmark critical functions
  • Test with large datasets
  • Monitor memory usage
func BenchmarkPingTool_Execute(b *testing.B) {
    tool := &PingTool{}
    params := PingParameters{
        Host:  "8.8.8.8",
        Count: 4,
    }
    
    b.ResetTimer()
    for i := 0; i < b.N; i++ {
        _, err := tool.Execute(context.Background(), params)
        if err != nil {
            b.Fatal(err)
        }
    }
}

Documentation​

Code Documentation​

  • Document all public functions and types
  • Use Go doc comments
  • Include examples for complex functions
// PingTool implements the DiagnosticTool interface for network ping operations.
// It provides ICMP ping functionality with configurable parameters.
type PingTool struct {
    client NetworkClient
}

// Execute performs a ping operation to the specified host.
// It returns a PingResult containing packet information and statistics.
//
// Example:
//   tool := &PingTool{client: networkClient}
//   result, err := tool.Execute(ctx, PingParameters{
//       Host: "google.com",
//       Count: 4,
//   })
func (p *PingTool) Execute(ctx context.Context, params Parameters) (Result, error) {
    // Implementation...
}

User Documentation​

  • Update README.md for new features
  • Add examples and use cases
  • Update configuration documentation
  • Add troubleshooting guides

Pull Request Process​

Before Submitting​

  1. Ensure all tests pass

    go test ./...

  2. Check code style

    go fmt ./...
    go vet ./...

  3. Update documentation

    • Update README.md if needed
    • Add/update doc comments
    • Update configuration docs

  4. Test your changes

    • Test on different platforms
    • Test with different configurations
    • Test edge cases

Pull Request Template​

When creating a pull request, include:

  • Description: What changes were made and why
  • Type: Feature, bug fix, documentation, etc.
  • Testing: How the changes were tested
  • Breaking Changes: Any breaking changes
  • Screenshots: For UI changes
  • Checklist: Ensure all items are completed

Review Process​

  1. Automated Checks: CI/CD pipeline runs tests and checks
  2. Code Review: Maintainers review the code
  3. Testing: Changes are tested in different environments
  4. Approval: At least one maintainer must approve
  5. Merge: Changes are merged to main branch

Issue Reporting​

Bug Reports​

When reporting bugs, include:

  • Description: Clear description of the issue
  • Steps to Reproduce: Detailed steps
  • Expected Behavior: What should happen
  • Actual Behavior: What actually happens
  • Environment: OS, Go version, etc.
  • Logs: Relevant error messages or logs

Feature Requests​

When requesting features, include:

  • Description: Clear description of the feature
  • Use Case: Why this feature is needed
  • Proposed Solution: How you think it should work
  • Alternatives: Other solutions considered

Community Guidelines​

Code of Conduct​

  • Be respectful and inclusive
  • Focus on constructive feedback
  • Help others learn
  • Follow the project's coding standards

Getting Help​

  • Check existing issues and discussions
  • Ask questions in GitHub Discussions
  • Join our Discord community
  • Read the documentation

Release Process​

Versioning​

We follow Semantic Versioning:

  • MAJOR: Breaking changes
  • MINOR: New features (backward compatible)
  • PATCH: Bug fixes (backward compatible)

Release Checklist​

  • All tests pass
  • Documentation updated
  • Changelog updated
  • Version bumped
  • Release notes prepared
  • Tag created
  • Release published

Recognition​

Contributors are recognized in:

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

Thank you for contributing to NetTraceX! 🚀