Contributing Guide

​

Ways to Contribute

• Report bugs - Found an issue? Let us know!
• Suggest features - Have an idea for improvement? Share it!
• Fix bugs - Submit a pull request to fix an existing issue
• Add features - Implement new functionality
• Improve documentation - Help make the docs better
• Write tests - Increase test coverage
• Review pull requests - Help review community contributions

​

Before You Start

​

Contributor License Agreement

​

Development Setup

​

Prerequisites

• Go 1.21 or later (for the Go implementation)
• Git for version control
• Make for building the project
• kubectl for testing
• A Kubernetes cluster for testing (minikube, kind, or real cluster)

​

Clone the Repository

git clone https://github.com/ahmetb/kubectx.git
cd kubectx

​

Build the Project

# Build both kubectx and kubens
make

# Build only kubectx
make kubectx

# Build only kubens
make kubens

​

Run Tests

# Run all tests
make test

# Run tests for a specific package
go test ./cmd/kubectx/...
go test ./cmd/kubens/...

​

Making Changes

​

1. Create an Issue First

1. Check if an issue already exists for your idea
2. If not, create a new issue describing:
   • The problem you’re solving
   • Your proposed solution
   • Any alternatives you considered

​

2. Fork and Branch

# Fork the repository on GitHub, then:
git clone https://github.com/YOUR_USERNAME/kubectx.git
cd kubectx

# Create a feature branch
git checkout -b feature/your-feature-name

• feature/ - for new features
• fix/ - for bug fixes
• docs/ - for documentation changes
• refactor/ - for code refactoring

​

3. Make Your Changes

• Follow Effective Go guidelines
• Use go fmt to format your code
• Run go vet to check for common mistakes
• Add tests for new functionality
• Update existing tests if behavior changes

• Use shellcheck to validate scripts
• Follow existing code style
• Add comments for complex logic

• Update README.md if adding new features
• Update help text in code
• Add code comments for complex logic

​

4. Write Tests

// Example test structure
func TestYourFeature(t *testing.T) {
    // Arrange
    // Set up test data
    
    // Act
    // Call the function being tested
    
    // Assert
    // Verify the results
}

make test

​

5. Commit Your Changes

git add .
git commit -m "Add feature: interactive deletion with multi-select"

• Use present tense (“Add feature” not “Added feature”)
• First line should be 50 characters or less
• Add detailed description after a blank line if needed
• Reference issue numbers (e.g., “Fixes #123”)

​

6. Push and Create Pull Request

git push origin feature/your-feature-name

• Clear title - Summarize the change
• Description - Explain what, why, and how
• Issue reference - Link to related issues
• Testing - Describe how you tested the change
• Screenshots - If applicable (for UI changes)

​

Code Review Process

​

What to Expect

• Initial review: Usually within a few days
• Feedback iterations: Varies based on complexity
• Merge: After all feedback is addressed and tests pass

• Request changes to code style
• Ask for additional tests
• Suggest architectural improvements
• Request documentation updates

​

Responding to Feedback

1. Make the requested changes in your branch
2. Commit and push the updates
3. Reply to review comments explaining your changes
4. Mark conversations as resolved when addressed

# Make changes based on review
git add .
git commit -m "Address review feedback: improve error handling"
git push origin feature/your-feature-name

​

Getting Your PR Merged

• All review feedback is addressed
• All tests pass (CI checks are green)
• The CLA is signed
• At least one maintainer approves
• No merge conflicts exist

​

Testing Guidelines

​

Manual Testing

# Build the binaries
make

# Test kubectx
./kubectx                    # List contexts
./kubectx minikube          # Switch context
./kubectx -                 # Switch to previous
./kubectx -c                # Show current
./kubectx new=old           # Rename
./kubectx -d test           # Delete

# Test kubens
./kubens                    # List namespaces
./kubens kube-system       # Switch namespace
./kubens -                 # Switch to previous
./kubens -c                # Show current
./kubens test --force      # Force switch

​

Automated Testing

# Run unit tests
make test

# Run specific test
go test -v ./cmd/kubectx/ -run TestSpecificFunction

# Check test coverage
go test -cover ./cmd/kubectx/...
go test -cover ./cmd/kubens/...

​

Documentation Contributions

​

README Updates

1. Update the main README.md
2. Update relevant examples
3. Add new sections if introducing features

​

Code Documentation

// Add godoc comments for exported functions
// Example follows Go documentation standards
//
// SwitchContext changes the active context to the specified name.
// It returns an error if the context does not exist or cannot be set.
func SwitchContext(name string) error {
    // Implementation
}

​

Help Text

// cmd/kubectx/help.go or cmd/kubens/help.go
const helpText = `USAGE:
  kubectx <NEW_COMMAND>        : description of new command
`

​

Common Contribution Scenarios

​

Adding a New Command

1. Add command parsing in flags.go
2. Create operation struct and Run() method
3. Add help text in help.go
4. Write unit tests
5. Update README.md
6. Test manually

​

Fixing a Bug

1. Write a test that reproduces the bug
2. Verify the test fails
3. Fix the bug
4. Verify the test passes
5. Submit PR with test and fix

​

Improving Error Messages

1. Identify unclear error messages
2. Update error text to be more descriptive
3. Ensure errors include context
4. Test error paths manually

​

Getting Help

• Ask in the issue - Comment on the related issue
• GitHub Discussions - Start a discussion for general questions
• Pull Request - Ask questions in your PR description or comments
• Review existing code - Look at similar features for guidance

​

Release Process

• MAJOR - Incompatible API changes
• MINOR - New functionality (backward compatible)
• PATCH - Bug fixes (backward compatible)

​

Code of Conduct

• Be respectful and considerate
• Welcome newcomers and help them get started
• Focus on constructive feedback
• Assume good intentions
• Respect differing viewpoints and experiences

​

Recognition

• GitHub contributors list
• Release notes (for significant contributions)
• Project README (for major features)

​

Quick Reference

# Setup
git clone https://github.com/ahmetb/kubectx.git
cd kubectx

# Build
make

# Test
make test

# Create PR
git checkout -b feature/my-feature
# Make changes
git commit -m "Add feature: description"
git push origin feature/my-feature
# Create PR on GitHub

​

Additional Resources

• GitHub Repository
• Issue Tracker
• Pull Requests
• GitHub Help - Pull Requests
• Effective Go