1 # CONTRIBUTING 2 3 The libuv project welcomes new contributors. This document will guide you 4 through the process. 5 6 7 ### FORK 8 9 Fork the project [on GitHub](https://github.com/libuv/libuv) and check out 10 your 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 18 Now decide if you want your feature or bug fix to go into the master branch 19 or the stable branch. As a rule of thumb, bug fixes go into the stable branch 20 while new features go into the master branch. 21 22 The stable branch is effectively frozen; patches that change the libuv 23 API/ABI or affect the run-time behavior of applications get rejected. 24 25 In case of doubt, open an issue in the [issue tracker][], post your question 26 to the [libuv discussions forum], or message the [libuv mailing list]. 27 28 Especially do so if you plan to work on something big. Nothing is more 29 frustrating than seeing your hard work go to waste because your vision does not 30 align with that of the [project maintainers]. 31 32 33 ### BRANCH 34 35 Okay, so you have decided on the proper branch. Create a feature branch 36 and 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 46 Please adhere to libuv's code style. In general it follows the conventions from 47 the [Google C/C++ style guide]. Some of the key points, as well as some 48 additional 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 89 Make 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 (a] example.com" 94 ``` 95 96 Writing good commit logs is important. A commit log should describe what 97 changed and why. Follow these guidelines when writing one: 98 99 1. 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"). 102 2. Keep the second line blank. 103 3. Wrap all other lines at 72 columns. 104 105 A good commit log looks like this: 106 107 ``` 108 subsystem: explaining the commit in one line 109 110 Body of commit message is a few lines of text, explaining things 111 in more detail, possibly giving some background about the issue 112 being fixed, etc etc. 113 114 The body of the commit message can be several paragraphs, and 115 please do proper word-wrap and keep columns shorter than about 116 72 characters or so. That way `git log` will show things 117 nicely even when it is indented. 118 ``` 119 120 The header line should be meaningful; it is what other people see when they 121 run `git shortlog` or `git log --oneline`. 122 123 Check the output of `git log --oneline files_that_you_changed` to find out 124 what subsystem (or subsystems) your changes touch. 125 126 127 ### REBASE 128 129 Use `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 139 Bug 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 142 If 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 146 Look at other tests to see how they should be structured (license boilerplate, 147 the way entry points are declared, etc.). 148 149 Check README.md file to find out how to run the test suite and make sure that 150 there are no test regressions. 151 152 ### PUSH 153 154 ``` 155 $ git push origin my-feature-branch 156 ``` 157 158 Go to https://github.com/username/libuv and select your feature branch. Click 159 the 'Pull Request' button and fill out the form. 160 161 Pull requests are usually reviewed within a few days. If there are comments 162 to address, apply your changes in a separate commit and push that to your 163 feature branch. Post a comment in the pull request afterwards; GitHub does 164 not 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
Indexes created Mon Apr 20 00:23:12 UTC 2026