WordPress is a community effort, as is the WP-API; this client library should be, too. We welcome contributions, however big or small!
This document outlines some of the best practices and conventions used within this project, with links to the libraries and tools we use for testing, syntax checking, and so on.
You should always run npm test before committing, to identify any syntax, style or unit test errors in your branch.
A single commit should encompass a single, related set of changes. Work on different features should be addressed in different commit. We do not squash commits when merging pull requests, in order to preserve this granular history.
Thanks to the WP-API project for these examples
Commit messages should follow the standard laid out in the git manual; that is, a one-line summary, followed by longer explanatory text when necessary.
Short (50 chars or less) summary of changes
More detailed explanatory text, if necessary. Wrap it to about 75
characters or so. In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body. The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.
Further paragraphs come after blank lines.
- Bullet points are okay, too
- Typically a hyphen or asterisk is used for the bullet, preceded by a
single space, with blank lines in between, but conventions vary here
Changes are proposed in the form of pull requests submitted by you, the contributor! After submitting your proposed changes, a member of the library's development team will review your commits and discuss any necessary changes with you in the PR comment thread. Your pull request will then be merged after final review.
We rebase feature branches onto master when merging in order to maintain a linear history, so committers should avoid using the Big Green Button.
We use JSCS to enforce a basic set of code style guidelines, and JSHint to guard against syntax errors. To run them both execute npm run lint (or grunt jscs jshint, if you have the Grunt command-line tool installed).
JSCS is a useful tool for enforcing a code style, but isn't flexible enough to cover all guidelines. Note our standard for spacing within function parentheses, which is not enforced mechanically but will be evaluated manually when reviewing pull requests:
// Function params and args should be spaced out from the parentheses:
someMethodCall( param1, param2 );
function newFunction( arg1, arg2 ) {};"When in doubt, space it out," with the following exceptions.
// The space can be omitted when passing function expressions, object literals
// or array literals as arguments:
someMethodCall(function() {
// do stuff
});
someOtherMethod({
object: 'no space before an object literal'
}, 'but this String argument still has a space after it' );
someMethodThatTakesAnArray([
'no',
'leading or trailing',
'spaces needed'
]);We prefer camelCase variable and function names, and UpperCamelCase constructors. When using the underscore_case parameter names that are required by the WordPress API, the following JSHint directive can be used to disable the case enforcement for that particular file:
/*jshint -W106 */// Disable underscore_case warnings in this fileRun the existing tests with npm run mocha (or grunt test, if you have the Grunt command-line interface installed).
Adding new code, or submitting a pull request? If it does something, it should have tests! Under the hood we use Mocha to run our tests, and write our assertions using Chai's "expect" BDD syntax, e.g.:
expect( wp._options.endpoint ).to.equal( 'http://some.url.com/wp-json/' );If you are uncomfortable or unfamiliar with writing unit tests, you should feel free to submit a pull request without them! We'll work with you in the PR comments to walk you through how to test the code.
We use Sinon.js for spying on and stubbing functionality. Sinon assertions should also be written with the BDD style, which is enabled via sinon-chai:
expect( mockAgent.get ).to.have.been.calledWith( 'url/' );See the existing test files for more examples.
When testing code that uses 3rd-party modules, mocks may be injected for those dependencies by using the sandboxed-module package. See the WPRequest tests for example usage.
The README getting started guide & YUIDoc block comment should be kept up-to-date with feature development: If you aren't familiar with adding doc blocks, we'll help you work through it in the comments of your PR.
The API docs will be updated whenever a new NPM module version is published. No files within docs/ should be committed in any branch other than gh-pages.
To generate the docs yourself, run npm run docs (aliased to grunt yuidoc).
Internally, we try to use the following branch naming scheme to keep things organized:
- feature/feature-name: New features & enhancements (optionally, "feature/feature-name-[Github Issue/PR #]")
- bug/bug-name-[Github Issue #]: Bug fixes: these should always have a corresponding GH issue.
- refactor/feature-name: Architectural changes, refactoring
- build/feature-name: Features relating to the build process, Gruntfile, linting or testing process, NPM package, etcetera
- docs/feature-name: Documentation, README, contributing guide, fleshing out inline doc blocks; anything in the repository that's authored to be human-readable
It is not essential to maintain this naming structure in your own branches, though it is preferred; the important thing is that pull requests not be submitted from your master branch.
All code contributed to this repository will be licensed under the MIT license. Code you contribute should be owned by you, and by submitting a pull request you assert that the Node WordPress REST API client team has the authority to license that code to other people.