1# CONTRIBUTING 2 3The libuv project welcomes new contributors. This document will guide you 4through the process. 5 6 7### FORK 8 9Fork the project [on GitHub](https://github.com/libuv/libuv) and check out 10your copy. 11 12``` 13$ git clone https://github.com/username/libuv.git 14$ cd libuv 15$ git remote add upstream https://github.com/libuv/libuv.git 16``` 17 18Now decide if you want your feature or bug fix to go into the master branch 19or the stable branch. As a rule of thumb, bug fixes go into the stable branch 20while new features go into the master branch. 21 22The stable branch is effectively frozen; patches that change the libuv 23API/ABI or affect the run-time behavior of applications get rejected. 24 25In case of doubt, open an issue in the [issue tracker][], post your question 26to the [libuv discussions forum], or message the [libuv mailing list]. 27 28Especially do so if you plan to work on something big. Nothing is more 29frustrating than seeing your hard work go to waste because your vision does not 30align with that of the [project maintainers]. 31 32 33### BRANCH 34 35Okay, so you have decided on the proper branch. Create a feature branch 36and start hacking: 37 38``` 39$ git checkout -b my-feature-branch -t origin/v1.x 40``` 41 42(Where v1.x is the latest stable branch as of this writing.) 43 44### CODE 45 46Please adhere to libuv's code style. In general it follows the conventions from 47the [Google C/C++ style guide]. Some of the key points, as well as some 48additional guidelines, are enumerated below. 49 50* Code that is specific to unix-y platforms should be placed in `src/unix`, and 51 declarations go into `include/uv/unix.h`. 52 53* Source code that is Windows-specific goes into `src/win`, and related 54 publicly exported types, functions and macro declarations should generally 55 be declared in `include/uv/win.h`. 56 57* Names should be descriptive and concise. 58 59* All the symbols and types that libuv makes available publicly should be 60 prefixed with `uv_` (or `UV_` in case of macros). 61 62* Internal, non-static functions should be prefixed with `uv__`. 63 64* Use two spaces and no tabs. 65 66* Lines should be wrapped at 80 characters. 67 68* Ensure that lines have no trailing whitespace, and use unix-style (LF) line 69 endings. 70 71* Use C89-compliant syntax. In other words, variables can only be declared at 72 the top of a scope (function, if/for/while-block). 73 74* When writing comments, use properly constructed sentences, including 75 punctuation. 76 77* When documenting APIs and/or source code, don't make assumptions or make 78 implications about race, gender, religion, political orientation or anything 79 else that isn't relevant to the project. 80 81* Remember that source code usually gets written once and read often: ensure 82 the reader doesn't have to make guesses. Make sure that the purpose and inner 83 logic are either obvious to a reasonably skilled professional, or add a 84 comment that explains it. 85 86 87### COMMIT 88 89Make sure git knows your name and email address: 90 91``` 92$ git config --global user.name "J. Random User" 93$ git config --global user.email "j.random.user@example.com" 94``` 95 96Writing good commit logs is important. A commit log should describe what 97changed and why. Follow these guidelines when writing one: 98 991. The first line should be 50 characters or less and contain a short 100 description of the change prefixed with the name of the changed 101 subsystem (e.g. "net: add localAddress and localPort to Socket"). 1022. Keep the second line blank. 1033. Wrap all other lines at 72 columns. 104 105A good commit log looks like this: 106 107``` 108subsystem: explaining the commit in one line 109 110Body of commit message is a few lines of text, explaining things 111in more detail, possibly giving some background about the issue 112being fixed, etc etc. 113 114The body of the commit message can be several paragraphs, and 115please do proper word-wrap and keep columns shorter than about 11672 characters or so. That way `git log` will show things 117nicely even when it is indented. 118``` 119 120The header line should be meaningful; it is what other people see when they 121run `git shortlog` or `git log --oneline`. 122 123Check the output of `git log --oneline files_that_you_changed` to find out 124what subsystem (or subsystems) your changes touch. 125 126 127### REBASE 128 129Use `git rebase` (not `git merge`) to sync your work from time to time. 130 131``` 132$ git fetch upstream 133$ git rebase upstream/v1.x # or upstream/master 134``` 135 136 137### TEST 138 139Bug fixes and features should come with tests. Add your tests in the 140`test/` directory. Each new test needs to be registered in `test/test-list.h`. 141 142If you add a new test file, it needs to be registered in three places: 143- `CMakeLists.txt`: add the file's name to the `uv_test_sources` list. 144- `Makefile.am`: add the file's name to the `test_run_tests_SOURCES` list. 145 146Look at other tests to see how they should be structured (license boilerplate, 147the way entry points are declared, etc.). 148 149Check README.md file to find out how to run the test suite and make sure that 150there are no test regressions. 151 152### PUSH 153 154``` 155$ git push origin my-feature-branch 156``` 157 158Go to https://github.com/username/libuv and select your feature branch. Click 159the 'Pull Request' button and fill out the form. 160 161Pull requests are usually reviewed within a few days. If there are comments 162to address, apply your changes in a separate commit and push that to your 163feature branch. Post a comment in the pull request afterwards; GitHub does 164not send out notifications when you add commits. 165 166 167[issue tracker]: https://github.com/libuv/libuv/issues 168[libuv mailing list]: http://groups.google.com/group/libuv 169[libuv discussions forum]: https://github.com/libuv/libuv/discussions 170[Google C/C++ style guide]: https://google.github.io/styleguide/cppguide.html 171[project maintainers]: https://github.com/libuv/libuv/blob/master/MAINTAINERS.md 172
