Contributing
Most of this documentation should be migrated to the website it is left here for now for historical purposes, please contribute to documentation on the website repository
The only “official” node repository is https://github.com/joyent/node. For code, docs, tests, or anything else, joyent/node is the repository that reflects the official state of the Node.js project. That’s where all patches have to end up if they are going to be in the release, website, or API docs. To submit a patch fork the repository and send a pull request via GitHub to joyent/node.
- Read CONTRIBUTING.md document
- Discuss large changes on the mailing list before coding
- JavaScript code style should follow Google’s JavaScript style guide and be run through the linter.
make jslintto validate. - C++ code should follow Google’s C++ style guide and be run through cpplint with
make cpplint. - Node follows the even/odd version numbering for changes:
- API changes, including new APIs will usually not go into even version numbers
- Bug fixes and documentation changes may go into even versions
- Most development happens on the “master” branch, which is always an odd version
- Applicable changes to the current stable version will usually be backported from master
- A pull request on GitHub is the easiest way to get code into node — it allows the core developers to keep a track of the changes
Node uses an automated test suite run via “make test”. To create a new test file, select an appropriate subdirectory of “test/” and create a file named “test-<something>.js” – where the “<something>” indicates what is being tested. See the other tests in those directories for examples of how to write tests. Generally this involves calling assert.equal() to check things match your expected outcome. Every new feature MUST have tests or it will not be accepted into the node core.
- The first line should have a maximum of 50 columns.
- The second line should be blank.
- Any additional lines should not exceed 72 columns.
- The author field should be properly filled out with your full name and email address.
To generate patch files:
- Clone the Git repository.
- Make your change. Remember to update tests and docs as well as code!
- Commit your change.
- Use the
git format-patchcommand to generate patch files.
For more detailed information on managing a Git repo, please visit the Contributing for Dummies page.
These are some things to consider before thinking about patching node core:
- Does the concept match the general goals of Node? Your patch needs to be aligned with Node’s core goals – to provide a fast, lightweight framework for building networked applications.
- Is your patch backwards compatible? Breaking backwards compatibility is never done lightly.
- Is your patch cross platform? Will it work on Windows as well as Unix-like OS’s?
- Could your patch be a module? Node intends to keep the core as lightweight as possible. Consider creating a module and uploading to npm instead. See node-core vs. userland.
- Is the feature broadly useful? There’s no point adding features to Node that only you or a few people will use.
- Have you tested it? See the note about tests above.
- Have you documented it? Documentation is in the “docs” directory.
- Will this patch create more work for the Node developers? In short, is it adding to complexity?
