bosun.org@v0.0.0-20210513094433-e25bc3e69a1f/CONTRIBUTING.md (about)

     1  # Contributing to bosun and scollector
     2   
     3  We're glad you want to make a contribution!
     4   
     5  Fork this repository and send in a pull request when you're finished with your changes. Link any relevant issues in too.
     6   
     7  Take note of the build status of your pull request; only builds that pass will be accepted. 
     8  Please also keep to our conventions and style so we can keep this repository as clean as possible.
     9   
    10  ## Licence
    11   
    12  By contributing your code, you agree to licence your contribution under the terms of the [MIT licence].
    13   
    14  All files are released with the MIT licence.
    15  
    16  ## Before contributing
    17  
    18  If you're about to raise an issue because you think you've found a bug, or you'd like to request a feature, or for any other reason, please read this first.
    19  
    20  We're tracking issues in the issue tracker on GitHub. This includes bugs and feature requests. 
    21  It's not a support forum where we can answer questions about concrete Bosun instances or their configuration; unless, of course, they expose a bug in Bosun itself.
    22  
    23  Please use [StackOverflow] for support questions. There exists a Slack instance where general help questions can be asked or you can reach out to the developers. You can [request an invite here][SlackInvite].
    24  
    25  Please also see also our [Code of Conduct].
    26  
    27  ### Setting up your build system
    28  
    29  The repository contains a [Makefile] which should make it easy to install all dependencies. Other than that, 
    30  you're going to need a recent (1.13+) Go environment, NPM and GCC.
    31  Run the following targets to get all dependencies:
    32  - `make deps`
    33  - `make testdeps`  
    34  
    35  ### Bug reports
    36  
    37  A bug is a _demonstrable problem_ that is caused by the code in the repository. Good bug reports are extremely helpful - thank you!
    38  
    39  Guidelines for bug reports:
    40  
    41  1. **Use the GitHub issue search** — check if the issue has already been
    42     reported.
    43  
    44  1. **Check if the issue has been fixed** — look for [closed issues] 
    45     or try to reproduce it using the latest code on the `master` branch.
    46  
    47  A good bug report shouldn't leave others needing to chase you up for more information. 
    48  Be sure to include the details of your environment and relevant tests that demonstrate the failure.
    49  
    50  ### Feature requests
    51  
    52  Feature requests are very welcome. Please take a moment to make sure you consider the following:
    53  
    54  1. **Use the GitHub search** to see if a request for that feature already exists. 
    55     If so, please contribute to the issue instead of raising a new one.
    56  1. Take a moment to think about whether your idea fits with the scope and aims of the project.
    57  1. Remember, it's up to *you* to make a strong case to convince the maintainers of the merits of this feature. 
    58     Please provide as much detail and context as possible, this means explaining the use case and why it is likely to be common.
    59  
    60  ## Contributing code
    61  
    62  Thank you for contributing to Bosun :raised_hands:
    63  
    64  Before opening a pull request, please take a moment to raise an issue describing the change or addition you'd like to 
    65  contribute. We'll do our best to support and review contributions, but there will be some things that don't fit the 
    66  plans we have for the project, which we therefore cannot accept. Reaching out to us on an issue helps all of us to be on 
    67  the same page and can save valuable time.
    68  
    69  We're using Github's labels to tag certain issues that we'd like help with. If you're a first time contributor, look out
    70  for issues tagged with [good first issue] for some of the easier issues to get you up to speed with the code base.
    71  
    72  Use GitHub pull requests to submit code. General submission guidelines:
    73  
    74  1. Add/update unit tests for your new feature or fix 
    75  1. Use the available targets in the [Makefile] (especially `make checks`) to perform the checks on your code. 
    76  For the full list of validation checks that will be run by the CI tool, see [.travis.yaml] and the Actions tab in 
    77  Github.
    78  1. Add any new third party dependencies to the `go.mod` file
    79  1. The commit message should indicate what folder is being changed 
    80  (example: `cmd/scollector: new xyz collector` or `docs: fix typo in window function`)
    81  1. Documentation changes should be made in the same branch as code changes using the `docs` folder. 
    82  After the PR is approved is merged into the master branch it will show up on https://bosun.org 
    83  (and is rendered using Github Pages).  
    84  
    85  Unless otherwise noted, the source files are distributed under the MIT license found in the LICENSE file.
    86  
    87  ### Style guidelines
    88  
    89  We use the golang [Go code review comments] document as the basis for our style. 
    90  Take particular note of Error Strings, Mixed Caps, and Indent Error Flow sections. 
    91  Also we don't have blank lines within functions.
    92  
    93  The make target `checks` will be run to make sure that the basic style guidelines are adhered to and fail the build
    94  if they weren't.
    95  
    96  ### Bosun submission guidelines
    97  
    98  1. If changing HTML, JS, or other static content, run `make generate`.
    99  1. [typescript][typescript] is required if changing JS files. 
   100     Invoke bosun with `-w` to watch for `.ts` changes and automatically run typescript. 
   101     We currently use typescript 2.4.2: `npm i -g typescript@2.4.2` (or `make deps`)
   102  
   103  #### Note for vim users
   104  
   105  As vim will usually save file in a temporary buffer, then will rename the file. 
   106  So for the *-w* option to work, one could eventually at this in
   107  `.vimrc`, assuming GOPATH is the homedir:
   108  
   109  ```
   110  let &backupskip .= ',' . escape(expand('$HOME'), '\') . '/src/bosun.org/cmd/bosun/*.go'
   111  let &backupskip .= ',' . escape(expand('$HOME'), '\') . '/src/bosun.org/cmd/bosun/web/static/templates/*.html'
   112  let &backupskip .= ',' . escape(expand('$HOME'), '\') . '/src/bosun.org/cmd/bosun/web/static/js/*.ts'
   113  ```
   114  
   115  Or one could prefer the shorter version:
   116  
   117  ```
   118  set backupskip+=*/cmd/bosun/{*.go\\,web/static/{js/*.ts\\,templates/*.html}}
   119  ```
   120  
   121  ### scollector submission guidelines
   122  
   123  1. New scollector collectors must have units, types, and descriptions for all new metrics. 
   124     Descriptions should not be in the `Add()` line, but in another data structure or constant. 
   125     See [keepalive collectors] for the constants, and the [memcached] for good patterns.
   126  
   127  [Code of Conduct]: CODE_OF_CONDUCT.md "Code of Conduct"
   128  [MIT licence]: LICENSE "MIT licence"
   129  [closed issues]: https://github.com/bosun-monitor/bosun/issues?q=is%3Aissue+is%3Aclosed "closed issues"
   130  [StackOverflow]: https://stackoverflow.com/questions/tagged/bosun "StackOverflow"
   131  [SlackInvite]: https://bosun.org/slackInvite
   132  [Go code review comments]: https://github.com/golang/go/wiki/CodeReviewComments "Go code review comments"
   133  [typescript]: https://www.npmjs.com/package/typescript
   134  [keepalive collectors]: https://github.com/bosun-monitor/bosun/blob/master/cmd/scollector/collectors/keepalived_linux.go "keepalive collectors"
   135  [memcached]: https://github.com/bosun-monitor/bosun/blob/master/cmd/scollector/collectors/memcached_unix.go "memcached"
   136  [Makefile]: https://github.com/bosun-monitor/bosun/blob/master/Makefile "Makefile"
   137  [.travis.yaml]: https://github.com/bosun-monitor/bosun/blob/master/.travis.yaml "`.travis.yaml`"
   138  [good first issue]: https://github.com/bosun-monitor/bosun/labels/good%20first%20issue "good first issue"