|
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 |