CONTRIBUTING.md

   1 # CONTRIBUTING
   2
   3 The node.js 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/joyent/node) and check out
  10 your copy.
  11
  12 ```
  13 $ git clone git@github.com:username/node.git
  14 $ cd node
  15 $ git remote add upstream git://github.com/joyent/node.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 node.js
  23 API/ABI or affect the run-time behavior of applications get rejected.
  24
  25 The rules for the master branch are less strict; consult the
  26 [stability index page][] for details.
  27
  28 In a nutshell, modules are at varying levels of API stability.  Bug fixes are
  29 always welcome but API or behavioral  changes to modules at stability level 3
  30 and up are off-limits.
  31
  32 Node.js has several bundled dependencies in the deps/ and the tools/
  33 directories that are not part of the project proper.  Any changes to files
  34 in those directories or its subdirectories should be sent to their respective
  35 projects.  Do not send your patch to us, we cannot accept it.
  36
  37 In case of doubt, open an issue in the [issue tracker][], post your question
  38 to the [node.js mailing list][] or contact one of the [project maintainers][]
  39 on [IRC][].
  40
  41 Especially do so if you plan to work on something big.  Nothing is more
  42 frustrating than seeing your hard work go to waste because your vision
  43 does not align with that of a project maintainer.
  44
  45
  46 ### BRANCH
  47
  48 Okay, so you have decided on the proper branch.  Create a feature branch
  49 and start hacking:
  50
  51 ```
  52 $ git checkout -b my-feature-branch -t origin/v0.8
  53 ```
  54
  55 (Where v0.8 is the latest stable branch as of this writing.)
  56
  57
  58 ### COMMIT
  59
  60 Make sure git knows your name and email address:
  61
  62 ```
  63 $ git config --global user.name "J. Random User"
  64 $ git config --global user.email "j.random.user@example.com"
  65 ```
  66
  67 Writing good commit logs is important.  A commit log should describe what
  68 changed and why.  Follow these guidelines when writing one:
  69
  70 1. The first line should be 50 characters or less and contain a short
  71    description of the change.
  72 2. Keep the second line blank.
  73 3. Wrap all other lines at 72 columns.
  74
  75 A good commit log looks like this:
  76
  77 ```
  78 Header line: explaining the commit in one line
  79
  80 Body of commit message is a few lines of text, explaining things
  81 in more detail, possibly giving some background about the issue
  82 being fixed, etc etc.
  83
  84 The body of the commit message can be several paragraphs, and
  85 please do proper word-wrap and keep columns shorter than about
  86 72 characters or so. That way `git log` will show things
  87 nicely even when it is indented.
  88 ```
  89
  90 The header line should be meaningful; it is what other people see when they
  91 run `git shortlog` or `git log --oneline`.
  92
  93 Have a look at `git log` for inspiration.
  94
  95
  96 ### REBASE
  97
  98 Use `git rebase` (not `git merge`) to sync your work from time to time.
  99
 100 ```
 101 $ git fetch upstream
 102 $ git rebase upstream/v0.8  # or upstream/master
 103 ```
 104
 105
 106 ### TEST
 107
 108 Bug fixes and features should come with tests.  Add your tests in the
 109 test/simple/ directory.  Look at other tests to see how they should be
 110 structured (license boilerplate, common includes, etc.).
 111
 112 ```
 113 $ make jslint test
 114 ```
 115
 116 Make sure the linter is happy and that all tests pass.  Please, do not submit
 117 patches that fail either check.
 118
 119
 120 ### PUSH
 121
 122 ```
 123 $ git push origin my-feature-branch
 124 ```
 125
 126 Go to https://github.com/username/node and select your feature branch.  Click
 127 the 'Pull Request' button and fill out the form.
 128
 129 Pull requests are usually reviewed within a few days.  If there are comments
 130 to address, apply your changes in a separate commit and push that to your
 131 feature branch.  Post a comment in the pull request afterwards; GitHub does
 132 not send out notifications when you add commits.
 133
 134
 135 ### CONTRIBUTOR LICENSE AGREEMENT
 136
 137 Please visit http://nodejs.org/cla.html and sign the Contributor License
 138 Agreement.  You only need to do that once.
 139
 140
 141 [stability index page]: https://github.com/joyent/node/blob/master/doc/api/documentation.markdown
 142 [issue tracker]: https://github.com/joyent/node/issues
 143 [node.js mailing list]: http://groups.google.com/group/nodejs
 144 [IRC]: http://webchat.freenode.net/?channels=node.js
 145 [project maintainers]: https://github.com/joyent/node/wiki/Project-Organization