vendor/github.com/fsnotify/fsnotify/CONTRIBUTING.md

   1 # Contributing
   2
   3 ## Issues
   4
   5 * Request features and report bugs using the [GitHub Issue Tracker](https://github.com/fsnotify/fsnotify/issues).
   6 * Please indicate the platform you are using fsnotify on.
   7 * A code example to reproduce the problem is appreciated.
   8
   9 ## Pull Requests
  10
  11 ### Contributor License Agreement
  12
  13 fsnotify is derived from code in the [golang.org/x/exp](https://godoc.org/golang.org/x/exp) package and it may be included [in the standard library](https://github.com/fsnotify/fsnotify/issues/1) in the future. Therefore fsnotify carries the same [LICENSE](https://github.com/fsnotify/fsnotify/blob/master/LICENSE) as Go. Contributors retain their copyright, so you need to fill out a short form before we can accept your contribution: [Google Individual Contributor License Agreement](https://developers.google.com/open-source/cla/individual).
  14
  15 Please indicate that you have signed the CLA in your pull request.
  16
  17 ### How fsnotify is Developed
  18
  19 * Development is done on feature branches.
  20 * Tests are run on BSD, Linux, macOS and Windows.
  21 * Pull requests are reviewed and [applied to master][am] using [hub][].
  22   * Maintainers may modify or squash commits rather than asking contributors to.
  23 * To issue a new release, the maintainers will:
  24   * Update the CHANGELOG
  25   * Tag a version, which will become available through gopkg.in.
  26
  27 ### How to Fork
  28
  29 For smooth sailing, always use the original import path. Installing with `go get` makes this easy.
  30
  31 1. Install from GitHub (`go get -u github.com/fsnotify/fsnotify`)
  32 2. Create your feature branch (`git checkout -b my-new-feature`)
  33 3. Ensure everything works and the tests pass (see below)
  34 4. Commit your changes (`git commit -am 'Add some feature'`)
  35
  36 Contribute upstream:
  37
  38 1. Fork fsnotify on GitHub
  39 2. Add your remote (`git remote add fork git@github.com:mycompany/repo.git`)
  40 3. Push to the branch (`git push fork my-new-feature`)
  41 4. Create a new Pull Request on GitHub
  42
  43 This workflow is [thoroughly explained by Katrina Owen](https://splice.com/blog/contributing-open-source-git-repositories-go/).
  44
  45 ### Testing
  46
  47 fsnotify uses build tags to compile different code on Linux, BSD, macOS, and Windows.
  48
  49 Before doing a pull request, please do your best to test your changes on multiple platforms, and list which platforms you were able/unable to test on.
  50
  51 To aid in cross-platform testing there is a Vagrantfile for Linux and BSD.
  52
  53 * Install [Vagrant](http://www.vagrantup.com/) and [VirtualBox](https://www.virtualbox.org/)
  54 * Setup [Vagrant Gopher](https://github.com/nathany/vagrant-gopher) in your `src` folder.
  55 * Run `vagrant up` from the project folder. You can also setup just one box with `vagrant up linux` or `vagrant up bsd` (note: the BSD box doesn't support Windows hosts at this time, and NFS may prompt for your host OS password)
  56 * Once setup, you can run the test suite on a given OS with a single command `vagrant ssh linux -c 'cd fsnotify/fsnotify; go test'`.
  57 * When you're done, you will want to halt or destroy the Vagrant boxes.
  58
  59 Notice: fsnotify file system events won't trigger in shared folders. The tests get around this limitation by using the /tmp directory.
  60
  61 Right now there is no equivalent solution for Windows and macOS, but there are Windows VMs [freely available from Microsoft](http://www.modern.ie/en-us/virtualization-tools#downloads).
  62
  63 ### Maintainers
  64
  65 Help maintaining fsnotify is welcome. To be a maintainer:
  66
  67 * Submit a pull request and sign the CLA as above.
  68 * You must be able to run the test suite on Mac, Windows, Linux and BSD.
  69
  70 To keep master clean, the fsnotify project uses the "apply mail" workflow outlined in Nathaniel Talbott's post ["Merge pull request" Considered Harmful][am]. This requires installing [hub][].
  71
  72 All code changes should be internal pull requests.
  73
  74 Releases are tagged using [Semantic Versioning](http://semver.org/).
  75
  76 [hub]: https://github.com/github/hub
  77 [am]: http://blog.spreedly.com/2014/06/24/merge-pull-request-considered-harmful/#.VGa5yZPF_Zs