github.com/saucelabs/saucectl@v0.175.1/CONTRIBUTING.md (about)

     1  # Contributing to saucectl
     2  
     3  Want to hack on saucectl? Awesome! This page contains information about reporting issues as well as some tips and guidelines useful to experienced open source contributors.
     4  
     5  ## Topics
     6  
     7  * [Development Requirements](#development-requirements)
     8  * [Install](#install)
     9  * [Build](#build)
    10  * [Test](#test)
    11  * [Reporting Security Issues](#reporting-security-issues)
    12  * [Design and Cleanup Proposals](#design-and-cleanup-proposals)
    13  * [Reporting Issues](#reporting-other-issues)
    14  * [Quick Contribution Tips and Guidelines](#quick-contribution-tips-and-guidelines)
    15  * [Releasing saucectl](#releasing-saucectl)
    16  
    17  ## Development Requirements
    18  
    19  - [Go](https://golang.org/) (v1.16 or higher)
    20  - [Homebrew](https://brew.sh/) (v2.2.13 or higher)
    21  
    22  ## Install
    23  
    24  Run the following to install all dependencies:
    25  
    26  ```sh
    27  $ make install
    28  ```
    29  
    30  ## Build
    31  
    32  To build the project, run:
    33  
    34  ```sh
    35  $ make build
    36  ```
    37  
    38  ## Test
    39  
    40  To execute unit tests, run:
    41  
    42  ```sh
    43  $ make test
    44  ```
    45  
    46  ## Reporting security issues
    47  
    48  For information on handling security vulnerabilities, please see our [Reporting Security Issues](/SECURITY.md) documentation.
    49  
    50  ## Reporting other issues
    51  
    52  A great way to contribute to the project is to send a detailed report when you encounter an issue. We always appreciate a well-written, thorough bug report, and will thank you for it!
    53  
    54  Check that [our issue database](https://github.com/saucelabs/saucectl/issues) doesn't already include that problem or suggestion before submitting an issue. If you find a match, you can use the "subscribe" button to get notified on updates. Do *not* leave random "+1" or "I have this too" comments, as they only clutter the discussion, and don't help resolving it. However, if you have ways to reproduce the issue or have additional information that may help resolving the issue, please leave a comment.
    55  
    56  When reporting issues, always include the output of `saucectl -v`.
    57  
    58  Also include the steps required to reproduce the problem if possible and applicable. This information will help us review and fix your issue faster. When sending lengthy log-files, consider posting them as a gist (https://gist.github.com).
    59  
    60  Don't forget to remove sensitive data from your logfiles before posting (you can replace those parts with "REDACTED").
    61  
    62  ## Quick contribution tips and guidelines
    63  
    64  This section gives the experienced contributor some tips and guidelines.
    65  
    66  ### Pull requests are always welcome
    67  
    68  Not sure if that typo is worth a pull request? Found a bug and know how to fix it? Do it! We will appreciate it. Any significant improvement should be documented as [a GitHub issue](https://github.com/saucelabs/saucectl/issues) before anybody starts working on it.
    69  
    70  We are always thrilled to receive pull requests. We do our best to process them quickly.
    71  
    72  ### Conventions
    73  
    74  Fork the repository and make changes on your fork in a feature branch:
    75  
    76  - If it's a bug fix branch, name it XXXX-something where XXXX is the number of the issue. 
    77  - If it's a feature branch, create an enhancement issue to announce your intentions, and name it XXXX-something where XXXX is the number of the issue.
    78  
    79  Submit unit tests for your changes. Go has a great test framework built in; use it! Take a look at existing tests for inspiration. [Run the full test suite](README.md) on your branch before submitting a pull request.
    80  
    81  Update the documentation when creating or modifying features. Test your documentation changes for clarity, concision, and correctness, as well as a clean documentation build.
    82  
    83  Write clean code. Universally formatted code promotes ease of writing, reading, and maintenance. Always run `gofmt -s -w file.go` on each changed file before committing your changes. Most editors have plug-ins that do this automatically.
    84  
    85  Pull request descriptions should be as clear as possible and include a reference to all the issues that they address.
    86  
    87  Commit messages must start with a capitalized and short summary (max. 50 chars) written in the imperative, followed by an optional, more detailed explanatory text which is separated from the summary by an empty line.
    88  
    89  Code review comments may be added to your pull request. Discuss, then make the suggested modifications and push additional commits to your feature branch. Post a comment after pushing. New commits show up in the pull request automatically, but the reviewers are notified only when you comment.
    90  
    91  Pull requests must be cleanly rebased on top of master without multiple branches mixed into the PR.
    92  
    93  **Git tip**: If your PR no longer merges cleanly, use `rebase master` in your feature branch to update your pull request rather than `merge master`.
    94  
    95  After every commit, make sure the test suite passes. Include documentation changes in the same pull request so that a revert would remove all traces of the feature or fix.
    96  
    97  Include an issue reference like `Closes #XXXX` or `Fixes #XXXX` in the pull request description that close an issue. Including references automatically closes the issue on a merge.
    98  
    99  Please do not add yourself to the `AUTHORS` file, as it is regenerated regularly from the Git history.
   100  
   101  ## Coding Style
   102  
   103  Unless explicitly stated, we follow all coding guidelines from the Go community. While some of these standards may seem arbitrary, they somehow seem to result in a solid, consistent codebase.
   104  
   105  It is possible that the code base does not currently comply with these guidelines. We are not looking for a massive PR that fixes this, since that goes against the spirit of the guidelines. All new contributions should make a best effort to clean up and make the code base better than they left it. Obviously, apply your best judgement. Remember, the goal here is to make the code base easier for humans to navigate and understand. Always keep that in mind when nudging others to comply.
   106  
   107  The rules:
   108  
   109  1. All code should be formatted with `gofmt -s`.
   110  2. All code should pass the default levels of [`go vet`](https://pkg.go.dev/cmd/vet).
   111  3. All code should follow the guidelines covered in [Effective Go](http://golang.org/doc/effective_go.html) and [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments).
   112  4. Comment the code. Tell us the why, the history and the context.
   113  5. Document _all_ declarations and methods, even private ones. Declare expectations, caveats and anything else that may be important. If a type gets exported, having the comments already there will ensure it's ready.
   114  6. Variable name length should be proportional to its context and no longer. `noCommaALongVariableNameLikeThisIsNotMoreClearWhenASimpleCommentWouldDo`. In practice, short methods will have short variable names and globals will have longer names.
   115  7. No underscores in package names. If you need a compound name, step back, and re-examine why you need a compound name. If you still think you need a compound name, lose the underscore.
   116  8. No utils or helpers packages. If a function is not general enough to warrant its own package, it has not been written generally enough to be a part of a util package. Just leave it unexported and well-documented.
   117  9. All tests should run with `go test` and outside tooling should not be required. No, we don't need another unit testing framework. Assertion packages are acceptable if they provide _real_ incremental value.
   118  10. Even though we call these "rules" above, they are actually just guidelines. Since you've read all the rules, you now know that.
   119  
   120  If you are having trouble getting into the mood of idiomatic Go, we recommend reading through [Effective Go](https://golang.org/doc/effective_go.html). The [Go Blog](https://blog.golang.org) is also a great resource. Drinking the kool-aid is a lot easier than going thirsty.
   121  
   122  ## Releasing saucectl
   123  
   124  `saucectl` uses [GoReleaser](https://goreleaser.com/) to create releases. Everything that is required to do is to push a new tag upstream. A GitHub Actions [pipeline](https://github.com/saucelabs/saucectl-internal/actions?query=workflow%3A%22saucectl+release%22) is then triggered that runs GoReleaser with the right parameters. Before creating a new tag, check out the [latest releases](https://github.com/saucelabs/saucectl-internal/releases) and follow [semantic versioning](https://semver.org/).
   125  
   126  A release will automatically trigger:
   127  - an update to the [Homebrew Formulae](https://github.com/saucelabs/homebrew-saucectl)
   128  - a new release of [node-saucectl](https://github.com/saucelabs/node-saucectl)
   129  
   130  Double check that these updates have happened.