github.com/hoveychen/kafka-go@v0.4.42/CONTRIBUTING.md (about)

     1  # Contributing to kafka-go
     2  
     3  kafka-go is an open source project.  We welcome contributions to kafka-go of any kind including documentation,
     4  organization, tutorials, bug reports, issues, feature requests, feature implementations, pull requests, etc.
     5  
     6  ## Table of Contents
     7  
     8  * [Reporting Issues](#reporting-issues)
     9  * [Submitting Patches](#submitting-patches)
    10    * [Code Contribution Guidelines](#code-contribution-guidelines)
    11    * [Git Commit Message Guidelines](#git-commit-message-guidelines)
    12    * [Fetching the Source From GitHub](#fetching-the-sources-from-github)
    13    * [Building kafka-go with Your Changes](#building-kakfa-go-with-your-changes)
    14  
    15  ## Reporting Issues
    16  
    17  If you believe you have found a defect in kafka-go, use the GitHub issue tracker to report
    18  the problem to the maintainers.  
    19  When reporting the issue, please provide the version of kafka-go, what version(s) of Kafka 
    20  are you testing against, and your operating system.
    21  
    22   - [kafka-go Issues hoveychen/kafka-go](https://github.com/hoveychen/kafka-go/issues)
    23  
    24  ## Submitting Patches
    25  
    26  kafka-go project welcomes all contributors and contributions regardless of skill or experience levels.  If you are
    27  interested in helping with the project, we will help you with your contribution.
    28  
    29  ### Code Contribution
    30  
    31  To make contributions as seamless as possible, we ask the following:
    32  
    33  * Go ahead and fork the project and make your changes.  We encourage pull requests to allow for review and discussion of code changes.
    34  * When you’re ready to create a pull request, be sure to:
    35      * Have test cases for the new code. If you have questions about how to do this, please ask in your pull request.
    36      * Run `go fmt`.
    37      * Squash your commits into a single commit. `git rebase -i`. It’s okay to force update your pull request with `git push -f`.
    38      * Follow the **Git Commit Message Guidelines** below.
    39  
    40  ### Git Commit Message Guidelines
    41  
    42  This [blog article](http://chris.beams.io/posts/git-commit/) is a good resource for learning how to write good commit messages,
    43  the most important part being that each commit message should have a title/subject in imperative mood starting with a capital letter and no trailing period:
    44  *"Return error on wrong use of the Reader"*, **NOT** *"returning some error."*
    45  
    46  Also, if your commit references one or more GitHub issues, always end your commit message body with *See #1234* or *Fixes #1234*.
    47  Replace *1234* with the GitHub issue ID. The last example will close the issue when the commit is merged into *master*.
    48  
    49  Please use a short and descriptive branch name, e.g. NOT "patch-1". It's very common but creates a naming conflict each
    50  time when a submission is pulled for a review.
    51  
    52  An example:
    53  
    54  ```text
    55  Add Code of Conduct and Code Contribution Guidelines
    56  
    57  Add a full Code of Conduct and Code Contribution Guidelines document. 
    58  Provide description on how best to retrieve code, fork, checkout, and commit changes.
    59  
    60  Fixes #688
    61  ```
    62  
    63  ### Fetching the Sources From GitHub
    64  
    65  We use Go Modules support built into Go 1.11 to build.  The easiest way is to clone kafka-go into a directory outside of
    66  `GOPATH`, as in the following example:
    67  
    68  ```bash
    69  mkdir $HOME/src
    70  cd $HOME/src
    71  git clone https://github.com/hoveychen/kafka-go.git
    72  cd kafka-go
    73  go build ./...
    74  ```
    75  
    76  To make changes to kafka-go's source:
    77  
    78  1. Create a new branch for your changes (the branch name is arbitrary):
    79  
    80      ```bash
    81      git checkout -b branch1234
    82      ```
    83  
    84  1. After making your changes, commit them to your new branch:
    85  
    86      ```bash
    87      git commit -a -v
    88      ```
    89  
    90  1. Fork kafka-go in GitHub
    91  
    92  1. Add your fork as a new remote (the remote name, "upstream" in this example, is arbitrary):
    93  
    94      ```bash
    95      git remote add upstream git@github.com:USERNAME/kafka-go.git
    96      ```
    97  
    98  1. Push your branch (the remote name, "upstream" in this example, is arbitrary):
    99  
   100     ```bash
   101     git push upstream  
   102     ```
   103  
   104  1. You are now ready to submit a PR based upon the new branch in your forked repository.
   105  
   106  ### Using the forked library
   107  
   108  To replace the original version of kafka-go library with a forked version is accomplished this way.
   109  
   110  1. Make sure your application already has a go.mod entry depending on kafka-go
   111  
   112      ```bash
   113      module github.com/myusername/myapp
   114  
   115      require (
   116          ...
   117          github.com/hoveychen/kafka-go v1.2.3
   118          ...
   119      )
   120      ```
   121  
   122  1. Add the following entry to the beginning of the modules file.
   123  
   124      ```bash
   125      module github.com/myusername/myapp
   126  
   127      replace github.com/hoveychen/kafka-go v1.2.3 => ../local/directory
   128  
   129      require (
   130          ...
   131          github.com/hoveychen/kafka-go v1.2.3
   132          ...
   133      )
   134      ```
   135  1. Depending on if you are using `vendor`ing or not you might need to run the following command to pull in the new bits.
   136  
   137      ```bash
   138      > go mod vendor
   139      ```