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