1 # Contributing |
1 Thank you for your interest in contributing to fsnotify! We try to review and |
|
2 merge PRs in a reasonable timeframe, but please be aware that: |
2 |
3 |
3 ## Issues |
4 - To avoid "wasted" work, please discus changes on the issue tracker first. You |
|
5 can just send PRs, but they may end up being rejected for one reason or the |
|
6 other. |
4 |
7 |
5 * Request features and report bugs using the [GitHub Issue Tracker](https://github.com/fsnotify/fsnotify/issues). |
8 - fsnotify is a cross-platform library, and changes must work reasonably well on |
6 * Please indicate the platform you are using fsnotify on. |
9 all supported platforms. |
7 * A code example to reproduce the problem is appreciated. |
|
8 |
10 |
9 ## Pull Requests |
11 - Changes will need to be compatible; old code should still compile, and the |
|
12 runtime behaviour can't change in ways that are likely to lead to problems for |
|
13 users. |
10 |
14 |
11 ### Contributor License Agreement |
15 Testing |
|
16 ------- |
|
17 Just `go test ./...` runs all the tests; the CI runs this on all supported |
|
18 platforms. Testing different platforms locally can be done with something like |
|
19 [goon] or [Vagrant], but this isn't super-easy to set up at the moment. |
12 |
20 |
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). |
21 Use the `-short` flag to make the "stress test" run faster. |
14 |
22 |
15 Please indicate that you have signed the CLA in your pull request. |
|
16 |
23 |
17 ### How fsnotify is Developed |
24 [goon]: https://github.com/arp242/goon |
18 |
25 [Vagrant]: https://www.vagrantup.com/ |
19 * Development is done on feature branches. |
26 [integration_test.go]: /integration_test.go |
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 ### Maintainers |
|
52 |
|
53 Help maintaining fsnotify is welcome. To be a maintainer: |
|
54 |
|
55 * Submit a pull request and sign the CLA as above. |
|
56 * You must be able to run the test suite on Mac, Windows, Linux and BSD. |
|
57 |
|
58 All code changes should be internal pull requests. |
|
59 |
|
60 Releases are tagged using [Semantic Versioning](http://semver.org/). |
|