Contributing to Rancher

We welcome contributions to Rancher! This guide covers the contribution process, code standards, and community guidelines.

Getting Started

The official contribution guide is maintained at: Contributing to Rancher This guide provides comprehensive information about:

Setting up your development environment
Finding issues to work on
Submitting pull requests
Code review process
Community communication channels

Quick Start Guide

Prerequisites

GitHub account: Required for submitting PRs
Development environment: See Building Rancher
Sign the CLA: Contributor License Agreement (required for first contribution)

Fork and Clone

Fork the repository on GitHub

Clone your fork:

git clone https://github.com/YOUR_USERNAME/rancher.git
cd rancher

Add upstream remote:

git remote add upstream https://github.com/rancher/rancher.git

Verify remotes:

git remote -v
# origin    https://github.com/YOUR_USERNAME/rancher.git (fetch)
# origin    https://github.com/YOUR_USERNAME/rancher.git (push)
# upstream  https://github.com/rancher/rancher.git (fetch)
# upstream  https://github.com/rancher/rancher.git (push)

Development Workflow

Create a Feature Branch

Update your fork:

git fetch upstream
git checkout release/v2.8
git rebase upstream/release/v2.8

Create feature branch:
```
git checkout -b feature/my-new-feature
```

Make Changes

Write your code
- Follow Go coding conventions
- Add tests for new functionality
- Update documentation as needed

Run tests:

# Unit tests
go test ./...

# Integration tests (if applicable)
cd tests/v2/integration
go test -v ./...

Verify build:
```
make build
```

Commit Your Changes

Stage changes:
```
git add .
```

Commit with descriptive message:

git commit -m "Add feature: brief description

- Detailed explanation of changes
- Why the change was needed
- Any related issue numbers

Fixes #12345"

Push and Create Pull Request

Push to your fork:
```
git push origin feature/my-new-feature
```
Create pull request on GitHub:
- Navigate to your fork on GitHub
- Click “Compare & pull request”
- Fill in the PR template
- Reference related issues

Code Style Guidelines

Go Code Standards

Follow standard Go conventions:

Formatting:

# Format code
gofmt -w .

# Or use goimports (includes gofmt)
goimports -w .

Linting:

# Run golangci-lint
golangci-lint run

# Or install and run
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
golangci-lint run ./...

Code organization:
- Package names: lowercase, single word
- File names: lowercase, underscore-separated
- Keep files focused and cohesive

Naming Conventions

Variables and Functions:

// Good: descriptive, camelCase
func getUserByID(userID string) (*User, error) {
    var userName string
    // ...
}

// Avoid: abbreviations, unclear names
func get(id string) (*User, error) {
    var un string
    // ...
}

Constants:

// Good: CamelCase, exported when needed
const (
    DefaultTimeout = 30 * time.Second
    MaxRetries     = 3
)

Interfaces:

// Good: single method interfaces end in "er"
type Reader interface {
    Read(p []byte) (n int, err error)
}

// Good: descriptive names for complex interfaces
type UserManager interface {
    CreateUser(user *User) error
    GetUser(id string) (*User, error)
    DeleteUser(id string) error
}

Documentation

Package documentation:

// Package catalogv2 provides a set of tools for manipulating 
// Helm charts and Helm repositories, as well as managing 
// their dependencies.
package catalogv2

Function documentation:

// Index retrieves the Helm repository information for a specific 
// namespace and name. By default, it uses rancher version and the 
// local cluster's k8s version to filter available versions in the 
// returned index file.
//
// If skipFilter is true, it will return the entire unfiltered index file.
// If a valid targetK8sVersion is provided, it will filter versions based 
// on rancher version and the target k8s version.
func (c *Manager) Index(namespace, name, targetK8sVersion string, skipFilter bool) (*repo.IndexFile, error) {
    // ...
}

Comments:

Explain why, not what (code shows what)
Document exported functions, types, and constants
Use complete sentences
Start with the name of the item being documented

Error Handling

Always handle errors:

// Good: explicit error handling
data, err := readFile(filename)
if err != nil {
    return fmt.Errorf("reading file %s: %w", filename, err)
}

// Avoid: ignoring errors
data, _ := readFile(filename)

Wrap errors with context:

import "fmt"

if err != nil {
    return fmt.Errorf("failed to create user: %w", err)
}

Testing

Write tests for new code:

func TestGetUser(t *testing.T) {
    tests := []struct {
        name    string
        userID  string
        want    *User
        wantErr bool
    }{
        {
            name:   "valid user",
            userID: "user-123",
            want:   &User{ID: "user-123", Name: "Test User"},
        },
        {
            name:    "invalid user",
            userID:  "invalid",
            wantErr: true,
        },
    }
    
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            got, err := GetUser(tt.userID)
            if (err != nil) != tt.wantErr {
                t.Errorf("GetUser() error = %v, wantErr %v", err, tt.wantErr)
                return
            }
            if !reflect.DeepEqual(got, tt.want) {
                t.Errorf("GetUser() = %v, want %v", got, tt.want)
            }
        })
    }
}

Pull Request Process

Before Submitting

Checklist:

Code follows Go conventions and style guide
All tests pass: go test ./...
New code has test coverage
Documentation is updated
Commit messages are clear and descriptive
PR description explains the change
Related issues are referenced

PR Template

Fill out the PR template completely:

## Issue
Fixes #[issue number]

## Description
[Brief description of the change]

## Types of changes
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to change)
- [ ] Documentation update

## Testing
[Describe how you tested the changes]

## Screenshots (if applicable)
[Add screenshots to show UI changes]

## Checklist
- [ ] My code follows the code style of this project
- [ ] I have added tests to cover my changes
- [ ] All new and existing tests passed
- [ ] My change requires a change to the documentation
- [ ] I have updated the documentation accordingly

Code Review

Expect feedback:

Reviewers may request changes
Address all comments
Ask questions if something is unclear
Push updates to the same branch

Responding to feedback:

# Make requested changes
git add .
git commit -m "Address review feedback"
git push origin feature/my-new-feature

Merging

After approval:

Maintainers will merge your PR
The branch can be deleted after merging
Your contribution will be in the next release!

Issue Guidelines

Reporting Bugs

Before creating an issue:

Search existing issues
Check if it’s already fixed in latest version
Verify it’s a Rancher issue (not upstream)

Bug report template:

### Rancher Server Setup
- Rancher version: v2.8.0
- Installation option: Docker/Helm/etc.
- Kubernetes version: v1.28.0
- Docker version: 24.0.0

### Describe the bug
[Clear description of what the bug is]

### To Reproduce
Steps to reproduce:
1. Go to '...'
2. Click on '....'
3. See error

### Expected behavior
[What you expected to happen]

### Actual behavior
[What actually happened]

### Screenshots
[If applicable]

### Additional context
[Any other context about the problem]

Feature Requests

### Is your feature request related to a problem?
[Description of the problem]

### Describe the solution you'd like
[Clear description of what you want to happen]

### Describe alternatives you've considered
[Alternative solutions or features]

### Additional context
[Any other context or screenshots]

Community

Communication Channels

Rancher Forums:

forums.rancher.com
General discussion and questions
Announcements of new releases

Slack:

slack.rancher.io
Real-time chat with community and team
Technical discussions

GitHub:

github.com/rancher/rancher
Bug reports and feature requests
Pull requests and code reviews

Getting Help

Documentation: ranchermanager.docs.rancher.com
Forums: Ask questions in the forums
Slack: Join #rancher channel for quick questions
GitHub Issues: For bugs and feature requests

Security Issues

Do NOT open public issues for security vulnerabilities

Review security policy: github.com/rancher/rancher/security
Email security team: security-rancher@suse.com
Optional GPG key: Keybase

Best Practices

Development

Keep PRs focused: One feature or fix per PR
Write tests: Ensure good test coverage
Update docs: Keep documentation in sync with code
Rebase frequently: Keep your branch up to date
Squash commits: Before merging (if requested)

Communication

Be respectful: Follow the code of conduct
Be patient: Reviewers are volunteers
Be clear: Explain your reasoning
Be responsive: Address feedback promptly
Be helpful: Help others in the community

Code Quality

Follow conventions: Existing code style
Think about edge cases: Handle errors gracefully
Consider performance: Efficient implementations
Maintain backwards compatibility: When possible
Document public APIs: Clear and complete docs

Release Process

Versioning

Rancher follows semantic versioning:

Major (v2.x.x): Breaking changes
Minor (v2.8.x): New features, backwards compatible
Patch (v2.8.3): Bug fixes, backwards compatible

Branches

release/v2.8: Current stable branch
release/v2.9: Next minor version
master: Development branch (future major version)

Release Channels

Latest: Most recent stable release
Stable: Production-ready releases
Alpha: Preview of upcoming features

Additional Resources

Documentation

Official Docs: ranchermanager.docs.rancher.com
Contributing Guide: ranchermanager.docs.rancher.com/contribute-to-rancher
Build Guide: See Building Rancher

Code

Main Repository: github.com/rancher/rancher
Go Modules: See go.mod for dependencies
Contributing File: CONTRIBUTING.md

Support

Support Matrix: rancher.com/support-matrix
Commercial Support: Available from SUSE
Community Support: Forums and Slack

License

Acknowledgments

Thank you for contributing to Rancher! Your contributions help make Rancher better for everyone.

​Contributing to Rancher

​Getting Started

​Quick Start Guide

​Prerequisites

​Fork and Clone

​Development Workflow

​Create a Feature Branch

​Make Changes

​Commit Your Changes

​Push and Create Pull Request

​Code Style Guidelines

​Go Code Standards

​Naming Conventions

​Documentation

​Error Handling

​Testing

​Pull Request Process

​Before Submitting

​PR Template

​Code Review

​Merging

​Issue Guidelines

​Reporting Bugs

​Feature Requests

​Community

​Communication Channels

​Getting Help

​Security Issues

​Best Practices

​Development

​Communication

​Code Quality

​Release Process

​Versioning

​Branches

​Release Channels

​Additional Resources

​Documentation

​Code

​Support

​License

​Acknowledgments

Contributing to Rancher

Getting Started

Quick Start Guide

Prerequisites

Fork and Clone

Development Workflow

Create a Feature Branch

Make Changes

Commit Your Changes

Push and Create Pull Request

Code Style Guidelines

Go Code Standards

Naming Conventions

Documentation

Error Handling

Testing

Pull Request Process

Before Submitting

PR Template

Code Review

Merging

Issue Guidelines

Reporting Bugs

Feature Requests

Community

Communication Channels

Getting Help

Security Issues

Best Practices

Development

Communication

Code Quality

Release Process

Versioning

Branches

Release Channels

Additional Resources

Documentation

Code

Support

License

Acknowledgments