diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..6f6cb1f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,220 @@ +# Contributing to Deployd + +(Guidelines inspired by [AngularJS](https://github.com/angular/angular.js)) + +We'd love to have your contribution to deployd. There are several ways to contribute: + + * Build an external module for deployd + * Open bugs and feature requests for deployd core itself + * Submit Pull Requests to deployd core + +## Questions or Issues? + +The best place to start is to look at existing discussions in the [Deployd Users](https://groups.google.com/forum/#!forum/deployd-users) Google Group and to look at answered questions on Stack Overflow. +If an answer can't be found, the best bet is to post a new question +in the Google Group, or post an issue on Github if the issue +appears to be a bug in deployd core. + +### External Deployd Modules + +The goal of the deployd core is to be as lightweight +as possible, with simple APIs to build different +types of extensions. +In order to make deployd extensions discoverable in +[npm](http://npmjs.org), we recommend the +following naming conventions: + + * `dpd-module-xxx`, where `xxx` is the specific function + of this module. "Module" is the generic term for + anything that extends the functionality of deployd core. + * `dpd-resource-email`, where `email` is a unique + resource name. + In deployd, resources are any kind of data or + functionality that is intended to be made available + to client applications. + * `dpd-store-mongodb`, (Core API Pending) where + `mongodb` is a particular type of data store with + which to build deployd apps. + * `dpd-deploy-computeengine`, (Core API Pending) + where `computeengine` is a deployment target + for this deployd app + +The deployd documentation and dashboard will +likely implement features for discovering modules, +which will rely heavily on these established +naming conventions. + +### Bugs + +Helping to identify and report bugs is one +of the most helpful things folks can do to +contribute to deployd. + +See [Submitting Issues](#submitting-issues) below +for instructions on filing helpful bug reports. + +### Feature Requests + +Submitting feature requests is a helpful +way to let the core team and the rest of +the deployd community know how others are +using deployd, and how to make it better. + +Feature requests should be submitted as +issues or Pull Requests to the +[Github repository](https://github.com/deployd/deployd). + +## Submission Guidelines + +### Submitting Issues + +To help keep the issue count as low as it can be, +it's important to first review closed issues and forum +postings to make sure the issue is unreported and +valid. + +The best place to report bugs or issues with deployd +is on the [Github repository](https://github.com/deployd/deployd). + +When reporting a bug, it's important to include as +simple of an example as possible to help reproduce +the bug. Here are some helpful characteristics of a +bug report: + + * A simple description of the expected behavior + and actual behavior + * A failing unit test demonstrating the behavior + * A small code example (such as a resource + configuration file) to show the failure + * Which version of deployd-core, and versions of + third-party modules being used. + +### Submitting Pull Requests + +These are the guidelines for submitting +pull requests for new features or bugs: + + * Verify that the PR is not a duplicate + to another PR + * Make all changes in a new git branch + * Follow the established + [Code Submission Standards](#code-submission-standards) + * Follow the established + [Git Commit Guidelines](#git-commit-guidelines) + * See [Submitting Your Changes](#submitting-your-changes) + for details on finally submitting a PR + +## Code Submission Standards + +To ensure consistency in code style, keep these standards +in mind as you work on code to submit to deployd: + + * All features or bug fixes must be tested by + one or more specs in the `test` directory + * All public APIs must be documented in our + [docs](https://github.com/deployd/docs) + * JSHint should be run against all changes + without warnings by running `grunt jshint` + +## Git Commit Guidelines + +We have very precise rules over how our git commit messages can be formatted. +This leads to more readable messages that are easy to follow when looking through the project history. +But also, we use the git commit messages to generate the AngularJS change log. + +### Commit Message Format + +Each commit message consists of a **header**, a **body** and a **footer**. The header has a special +format that includes a **type**, a **scope** and a **subject**: + +``` +(): + + + +