Mercurial

comparison third_party/libuv/CONTRIBUTING.md @ 160:948de3f54cea

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[ThirdParty] Added libuv
author June Park <parkjune1995@gmail.com>
date Wed, 14 Jan 2026 19:39:52 -0800
parents
children
comparison
equal deleted inserted replaced
159:05cf9467a1c3 160:948de3f54cea
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 "[email protected]"
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