gobot.io/x/gobot/v2@v2.1.0/CONTRIBUTING.md (about)

     1  # Contributing to Gobot
     2  
     3  ## Target Branch
     4  
     5  **Please open all non-hotfix PRs against the `dev` branch!**
     6  
     7  Gobot follows a ["git flow"](http://nvie.com/posts/a-successful-git-branching-model/)-style model for managing development.
     8  
     9  ## Issue Contributions
    10  
    11  When opening new issues or commenting on existing issues on this repository
    12  please make sure discussions are related to concrete technical issues with the
    13  Gobot software.
    14  
    15  ## Code Contributions
    16  
    17  The Gobot project welcomes new contributors.
    18  
    19  This document will guide you through the contribution process.
    20  
    21  What do you want to contribute?
    22  
    23  * I want to otherwise correct or improve the docs or examples
    24  * I want to report a bug
    25  * I want to add some feature or functionality to an existing hardware platform
    26  * I want to add support for a new hardware platform
    27  
    28  Descriptions for each of these will eventually be provided below.
    29  
    30  ## General Guidelines
    31  
    32  * All active development is in the `dev` branch. New or updated features must be added to the `dev` branch. Hotfixes
    33    will be considered on the `master` branch in situations where it does not alter behavior or features, only fixes a bug.
    34  * All patches must be provided under the Apache 2.0 License
    35  * Please use the -S option in git to "sign off" that the commit is your work and you are providing it under the
    36    Apache 2.0 License
    37  * Submit a Github Pull Request to the appropriate branch and describe the changes sufficient.
    38  * Please follow our naming conventions for Pull Requests.
    39  * We will look at the patch, test it out, and give you feedback.
    40  * Avoid doing minor whitespace changes, renamings, etc. along with merged content. These will be done by the maintainers
    41    from time to time but they can complicate merges and should be done separately.
    42  * Take care to maintain the existing coding style.
    43  * `golangci-lint` your code, see [instruction for local installation](https://golangci-lint.run/usage/install/#local-installation)
    44  * `go fmt` your code (with the go version of go.mod)
    45  * Add unit tests for any new or changed functionality.
    46  * All pull requests should be "fast forward"
    47    * If there are commits after yours use “git rebase -i <new_head_branch>”
    48    * If you have local changes you may need to use “git stash”
    49    * For git help see [progit](http://git-scm.com/book) which is an awesome (and free) book on git
    50  
    51  ## Creating Pull Requests
    52  
    53  Because Gobot makes use of self-referencing import paths, you will want
    54  to implement the local copy of your fork as a remote on your copy of the
    55  original Gobot repo. Katrina Owen has [an excellent post on this workflow](https://splice.com/blog/contributing-open-source-git-repositories-go/).
    56  
    57  The basics are as follows:
    58  
    59  1. Fork the project via the GitHub UI
    60  
    61  2. `go get` the upstream repo and set it up as the `upstream` remote and your own repo as the `origin` remote:
    62  
    63      `go get gobot.io/x/gobot/v2`
    64      `cd $GOPATH/src/gobot.io/x/gobot`
    65      `git remote rename origin upstream`
    66      `git remote add origin git@github.com/YOUR_GITHUB_NAME/gobot`
    67  
    68      All import paths should now work fine assuming that you've got the
    69      proper branch checked out.
    70  
    71  3. Get all the needed gobot's dependencies each of them at their needed version. Gobot uses
    72     [dep (Dependency management for Go)](https://golang.github.io/dep/) to manage the project's dependencies. To get all
    73     the correct dependencies:
    74  
    75     * Install dep tool. Follow the dep [installation](https://golang.github.io/dep/docs/installation.html) instructions in
    76       case you don't have it already installed.
    77     * `cd $GOPATH/src/gobot.io/x/gobot`
    78     * `dep ensure` will fetch  all the dependencies at their needed version.
    79  
    80  ## Landing Pull Requests
    81  
    82  (This is for committers only. If you are unsure whether you are a committer, you are not.)
    83  
    84  1. Set the contributor's fork as an upstream on your checkout
    85  
    86     `git remote add contrib1 https://github.com/contrib1/gobot`
    87  
    88  2. Fetch the contributor's repo
    89  
    90     `git fetch contrib1`
    91  
    92  3. Checkout a copy of the PR branch
    93  
    94     `git checkout pr-1234 --track contrib1/branch-for-pr-1234`
    95  
    96  4. Review the PR as normal
    97  
    98  5. Land when you're ready via the GitHub UI
    99  
   100  ## Convention for Pull Request Descriptions
   101  
   102  Making unified descriptions helps a lot to generate the [CHANGELOG](./CHANGELOG.md) for the next release.
   103  We support the style from <https://www.conventionalcommits.org>, so you can use something like this:
   104  
   105  * type(scope): description
   106  * i2c(PCF8583): added
   107  * gpio(HD44780): fix wrong constants
   108  * raspi(PWM): refactor usage
   109  * docs(core): usage of Kernel driver
   110  * or alternative: core(docs): usage of Kernel driver
   111  * build(style): adjust rule for golangci-lint
   112  
   113  We try to keep it as simple as possible:
   114  
   115  * Do not use "fix" or "bugfix" for `type`
   116  * Please assign "fix", "style", "refactor", "perf", "test" etc. to the related `type` (driver-type/platform-name etc.),
   117    and start the description with e.g. "fix...", "test..." etc.
   118  * For `type` use the name of the deepest folder (e.g. i2c/raspi/system). Feel free to order "examples" to the
   119    related driver.
   120  * Further values for `type` are: "docs", "build", "core"
   121  * Please use "build" instead of "CI"
   122  * For the `scope` use the name of the driver or feature (e.g. grove/PWM).
   123  * If unsure don't panic, follow your feeling. Possibly the reviewer will correct it or suggest a better description.
   124  
   125  ## Developer's Certificate of Origin 1.0
   126  
   127  By making a contribution to this project, I certify that:
   128  
   129  * (a) The contribution was created in whole or in part by me and I
   130    have the right to submit it under the open source license indicated
   131    in the file; or
   132  * (b) The contribution is based upon previous work that, to the best
   133    of my knowledge, is covered under an appropriate open source license
   134    and I have the right under that license to submit that work with
   135    modifications, whether created in whole or in part by me, under the
   136    same open source license (unless I am permitted to submit under a
   137    different license), as indicated in the file; or
   138  * (c) The contribution was provided directly to me by some other
   139    person who certified (a), (b) or (c) and I have not modified it.
   140  
   141  ## Code of Conduct
   142  
   143  Gobot is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
   144  [You can read about it here](CODE_OF_CONDUCT.md).
   145  
   146  ## Origins
   147  
   148  This document is based on the original [io.js contribution guidelines](https://github.com/nodejs/io.js/blob/master/CONTRIBUTING.md)