Blame CONTRIBUTING.md

Packit b5b901
# CONTRIBUTING
Packit b5b901
Packit b5b901
The libuv project welcomes new contributors. This document will guide you
Packit b5b901
through the process.
Packit b5b901
Packit b5b901
Packit b5b901
### FORK
Packit b5b901
Packit b5b901
Fork the project [on GitHub](https://github.com/libuv/libuv) and check out
Packit b5b901
your copy.
Packit b5b901
Packit b5b901
```
Packit b5b901
$ git clone https://github.com/username/libuv.git
Packit b5b901
$ cd libuv
Packit b5b901
$ git remote add upstream https://github.com/libuv/libuv.git
Packit b5b901
```
Packit b5b901
Packit b5b901
Now decide if you want your feature or bug fix to go into the master branch
Packit b5b901
or the stable branch.  As a rule of thumb, bug fixes go into the stable branch
Packit b5b901
while new features go into the master branch.
Packit b5b901
Packit b5b901
The stable branch is effectively frozen; patches that change the libuv
Packit b5b901
API/ABI or affect the run-time behavior of applications get rejected.
Packit b5b901
Packit b5b901
In case of doubt, open an issue in the [issue tracker][], post your question
Packit b5b901
to the [libuv mailing list], or contact one of [project maintainers][] on [IRC][].
Packit b5b901
Packit b5b901
Especially do so if you plan to work on something big.  Nothing is more
Packit b5b901
frustrating than seeing your hard work go to waste because your vision
Packit b5b901
does not align with that of a project maintainers.
Packit b5b901
Packit b5b901
Packit b5b901
### BRANCH
Packit b5b901
Packit b5b901
Okay, so you have decided on the proper branch.  Create a feature branch
Packit b5b901
and start hacking:
Packit b5b901
Packit b5b901
```
Packit b5b901
$ git checkout -b my-feature-branch -t origin/v1.x
Packit b5b901
```
Packit b5b901
Packit b5b901
(Where v1.x is the latest stable branch as of this writing.)
Packit b5b901
Packit b5b901
### CODE
Packit b5b901
Packit b5b901
Please adhere to libuv's code style. In general it follows the conventions from
Packit b5b901
the [Google C/C++ style guide]. Some of the key points, as well as some
Packit b5b901
additional guidelines, are enumerated below.
Packit b5b901
Packit b5b901
* Code that is specific to unix-y platforms should be placed in `src/unix`, and
Packit Service e08953
  declarations go into `include/uv/unix.h`.
Packit b5b901
Packit b5b901
* Source code that is Windows-specific goes into `src/win`, and related
Packit b5b901
  publicly exported types, functions and macro declarations should generally
Packit Service e08953
  be declared in `include/uv/win.h`.
Packit b5b901
Packit b5b901
* Names should be descriptive and concise.
Packit b5b901
Packit b5b901
* All the symbols and types that libuv makes available publicly should be
Packit b5b901
  prefixed with `uv_` (or `UV_` in case of macros).
Packit b5b901
Packit b5b901
* Internal, non-static functions should be prefixed with `uv__`.
Packit b5b901
Packit b5b901
* Use two spaces and no tabs.
Packit b5b901
Packit b5b901
* Lines should be wrapped at 80 characters.
Packit b5b901
Packit b5b901
* Ensure that lines have no trailing whitespace, and use unix-style (LF) line
Packit b5b901
  endings.
Packit b5b901
Packit b5b901
* Use C89-compliant syntax. In other words, variables can only be declared at
Packit b5b901
  the top of a scope (function, if/for/while-block).
Packit b5b901
Packit b5b901
* When writing comments, use properly constructed sentences, including
Packit b5b901
  punctuation.
Packit b5b901
Packit b5b901
* When documenting APIs and/or source code, don't make assumptions or make
Packit b5b901
  implications about race, gender, religion, political orientation or anything
Packit b5b901
  else that isn't relevant to the project.
Packit b5b901
Packit b5b901
* Remember that source code usually gets written once and read often: ensure
Packit b5b901
  the reader doesn't have to make guesses. Make sure that the purpose and inner
Packit b5b901
  logic are either obvious to a reasonably skilled professional, or add a
Packit b5b901
  comment that explains it.
Packit b5b901
Packit b5b901
Packit b5b901
### COMMIT
Packit b5b901
Packit b5b901
Make sure git knows your name and email address:
Packit b5b901
Packit b5b901
```
Packit b5b901
$ git config --global user.name "J. Random User"
Packit b5b901
$ git config --global user.email "j.random.user@example.com"
Packit b5b901
```
Packit b5b901
Packit b5b901
Writing good commit logs is important.  A commit log should describe what
Packit b5b901
changed and why.  Follow these guidelines when writing one:
Packit b5b901
Packit b5b901
1. The first line should be 50 characters or less and contain a short
Packit b5b901
   description of the change prefixed with the name of the changed
Packit b5b901
   subsystem (e.g. "net: add localAddress and localPort to Socket").
Packit b5b901
2. Keep the second line blank.
Packit b5b901
3. Wrap all other lines at 72 columns.
Packit b5b901
Packit b5b901
A good commit log looks like this:
Packit b5b901
Packit b5b901
```
Packit b5b901
subsystem: explaining the commit in one line
Packit b5b901
Packit b5b901
Body of commit message is a few lines of text, explaining things
Packit b5b901
in more detail, possibly giving some background about the issue
Packit b5b901
being fixed, etc etc.
Packit b5b901
Packit b5b901
The body of the commit message can be several paragraphs, and
Packit b5b901
please do proper word-wrap and keep columns shorter than about
Packit b5b901
72 characters or so. That way `git log` will show things
Packit b5b901
nicely even when it is indented.
Packit b5b901
```
Packit b5b901
Packit b5b901
The header line should be meaningful; it is what other people see when they
Packit b5b901
run `git shortlog` or `git log --oneline`.
Packit b5b901
Packit b5b901
Check the output of `git log --oneline files_that_you_changed` to find out
Packit b5b901
what subsystem (or subsystems) your changes touch.
Packit b5b901
Packit b5b901
Packit b5b901
### REBASE
Packit b5b901
Packit b5b901
Use `git rebase` (not `git merge`) to sync your work from time to time.
Packit b5b901
Packit b5b901
```
Packit b5b901
$ git fetch upstream
Packit b5b901
$ git rebase upstream/v1.x  # or upstream/master
Packit b5b901
```
Packit b5b901
Packit b5b901
Packit b5b901
### TEST
Packit b5b901
Packit b5b901
Bug fixes and features should come with tests.  Add your tests in the
Packit b5b901
`test/` directory. Each new test needs to be registered in `test/test-list.h`.
Packit b5b901
Packit b5b901
If you add a new test file, it needs to be registered in three places:
Packit b5b901
- `CMakeLists.txt`: add the file's name to the `uv_test_sources` list.
Packit b5b901
- `Makefile.am`: add the file's name to the `test_run_tests_SOURCES` list.
Packit b5b901
Packit b5b901
Look at other tests to see how they should be structured (license boilerplate,
Packit b5b901
the way entry points are declared, etc.).
Packit b5b901
Packit b5b901
Check README.md file to find out how to run the test suite and make sure that
Packit b5b901
there are no test regressions.
Packit b5b901
Packit b5b901
### PUSH
Packit b5b901
Packit b5b901
```
Packit b5b901
$ git push origin my-feature-branch
Packit b5b901
```
Packit b5b901
Packit b5b901
Go to https://github.com/username/libuv and select your feature branch.  Click
Packit b5b901
the 'Pull Request' button and fill out the form.
Packit b5b901
Packit b5b901
Pull requests are usually reviewed within a few days.  If there are comments
Packit b5b901
to address, apply your changes in a separate commit and push that to your
Packit b5b901
feature branch.  Post a comment in the pull request afterwards; GitHub does
Packit b5b901
not send out notifications when you add commits.
Packit b5b901
Packit b5b901
Packit b5b901
[issue tracker]: https://github.com/libuv/libuv/issues
Packit b5b901
[libuv mailing list]: http://groups.google.com/group/libuv
Packit b5b901
[IRC]: http://webchat.freenode.net/?channels=libuv
Packit b5b901
[Google C/C++ style guide]: https://google.github.io/styleguide/cppguide.html
Packit b5b901
[project maintainers]: https://github.com/libuv/libuv/blob/master/MAINTAINERS.md