go-micro.dev/v5@v5.12.0/CONTRIBUTING.md (about)

     1  # Contributing to Go Micro
     2  
     3  Thank you for your interest in contributing to Go Micro! This document provides guidelines and instructions for contributing.
     4  
     5  ## Code of Conduct
     6  
     7  Be respectful, inclusive, and collaborative. We're all here to build great software together.
     8  
     9  ## Getting Started
    10  
    11  1. Fork the repository
    12  2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/go-micro.git`
    13  3. Add upstream remote: `git remote add upstream https://github.com/micro/go-micro.git`
    14  4. Create a feature branch: `git checkout -b feature/my-feature`
    15  
    16  ## Development Setup
    17  
    18  ```bash
    19  # Install dependencies
    20  go mod download
    21  
    22  # Run tests
    23  go test ./...
    24  
    25  # Run tests with coverage
    26  go test -race -coverprofile=coverage.out ./...
    27  
    28  # Run linter (install golangci-lint first)
    29  golangci-lint run
    30  ```
    31  
    32  ## Making Changes
    33  
    34  ### Code Guidelines
    35  
    36  - Follow standard Go conventions (use `gofmt`, `golint`)
    37  - Write clear, descriptive commit messages
    38  - Add tests for new functionality
    39  - Update documentation for API changes
    40  - Keep PRs focused - one feature/fix per PR
    41  
    42  ### Commit Messages
    43  
    44  Use conventional commits format:
    45  
    46  ```
    47  type(scope): subject
    48  
    49  body
    50  
    51  footer
    52  ```
    53  
    54  Types:
    55  - `feat`: New feature
    56  - `fix`: Bug fix
    57  - `docs`: Documentation changes
    58  - `test`: Test additions/changes
    59  - `refactor`: Code refactoring
    60  - `perf`: Performance improvements
    61  - `chore`: Maintenance tasks
    62  
    63  Examples:
    64  ```
    65  feat(registry): add kubernetes registry plugin
    66  fix(broker): resolve nats connection leak
    67  docs(examples): add streaming example
    68  ```
    69  
    70  ### Testing
    71  
    72  - Write unit tests for all new code
    73  - Ensure existing tests pass
    74  - Add integration tests for plugin implementations
    75  - Test with multiple Go versions (1.20+)
    76  
    77  ```bash
    78  # Run specific package tests
    79  go test ./registry/...
    80  
    81  # Run with verbose output
    82  go test -v ./...
    83  
    84  # Run specific test
    85  go test -run TestMyFunction ./pkg/...
    86  ```
    87  
    88  ### Documentation
    89  
    90  - Update relevant markdown files in `internal/website/docs/`
    91  - Add examples to `internal/website/docs/examples/` for new features
    92  - Update README.md for major features
    93  - Add godoc comments for exported functions/types
    94  
    95  ## Pull Request Process
    96  
    97  1. **Update your branch**
    98     ```bash
    99     git fetch upstream
   100     git rebase upstream/master
   101     ```
   102  
   103  2. **Run tests and linting**
   104     ```bash
   105     go test ./...
   106     golangci-lint run
   107     ```
   108  
   109  3. **Push to your fork**
   110     ```bash
   111     git push origin feature/my-feature
   112     ```
   113  
   114  4. **Create Pull Request**
   115     - Use a descriptive title
   116     - Reference any related issues
   117     - Describe what changed and why
   118     - Add screenshots for UI changes
   119     - Mark as draft if work in progress
   120  
   121  5. **PR Review**
   122     - Respond to feedback promptly
   123     - Make requested changes
   124     - Re-request review after updates
   125  
   126  ### PR Checklist
   127  
   128  - [ ] Tests pass locally
   129  - [ ] Code follows Go conventions
   130  - [ ] Documentation updated
   131  - [ ] Commit messages are clear
   132  - [ ] Branch is up to date with master
   133  - [ ] No merge conflicts
   134  
   135  ## Adding Plugins
   136  
   137  New plugins should:
   138  
   139  1. Live in the appropriate interface directory (e.g., `registry/myplugin/`)
   140  2. Implement the interface completely
   141  3. Include comprehensive tests
   142  4. Provide usage examples
   143  5. Document configuration options (env vars, options)
   144  6. Add to plugin documentation
   145  
   146  Example structure:
   147  ```
   148  registry/myplugin/
   149  ├── myplugin.go          # Main implementation
   150  ├── myplugin_test.go     # Tests
   151  ├── options.go           # Plugin-specific options
   152  └── README.md            # Usage and configuration
   153  ```
   154  
   155  ## Reporting Issues
   156  
   157  Before creating an issue:
   158  
   159  1. Search existing issues
   160  2. Check documentation
   161  3. Try the latest version
   162  
   163  When reporting bugs:
   164  - Use the bug report template
   165  - Include minimal reproduction code
   166  - Specify versions (Go, Go Micro, plugins)
   167  - Provide relevant logs
   168  
   169  ## Documentation Contributions
   170  
   171  Documentation improvements are always welcome!
   172  
   173  - Fix typos and grammar
   174  - Improve clarity
   175  - Add missing examples
   176  - Update outdated information
   177  
   178  Documentation lives in `internal/website/docs/`. Preview locally with Jekyll:
   179  
   180  ```bash
   181  cd internal/website
   182  bundle install
   183  bundle exec jekyll serve --livereload
   184  ```
   185  
   186  ## Community
   187  
   188  - GitHub Issues: Bug reports and feature requests
   189  - GitHub Discussions: Questions, ideas, and community chat
   190  - Sponsorship: [GitHub Sponsors](https://github.com/sponsors/micro)
   191  
   192  ## Release Process
   193  
   194  Maintainers handle releases:
   195  
   196  1. Update CHANGELOG.md
   197  2. Tag release: `git tag -a v5.x.x -m "Release v5.x.x"`
   198  3. Push tag: `git push origin v5.x.x`
   199  4. GitHub Actions creates release
   200  
   201  ## Questions?
   202  
   203  - Check [documentation](internal/website/docs/)
   204  - Browse [examples](internal/website/docs/examples/)
   205  - Open a [question issue](.github/ISSUE_TEMPLATE/question.md)
   206  
   207  Thank you for contributing to Go Micro! 🎉