diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..5f97a09 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,198 @@ +# Contributing + +Thanks for checking out Clay. We accept pull requests from anybody, however we ask +that you follow some conventions when contributing to Clay. + +We have set up a +[piece-of-cake](https://github.com/pebble/clay/issues?q=is%3Aopen+is%3Aissue+label%3Apiece-of-cake) +label in GitHub issues for bugs/features that are easy to implement. These issues are +a great place to start for people that are new to the codebase. + + +## Requirements + + - [Node](https://nodejs.org) (4.0 and later) + - [Google Chrome](www.google.com/chrome) (To run tests) + - [Pebble SDK](https://developer.pebble.com/sdk/) (optional) + + +## Getting Started + +### 1. Fork, then clone the repo: + +`$ git clone git@github.com:your-username/clay.git` + +### 2. Create a new branch with the following naming convention. + +`#/description-of-change` + +example: + +`#90/support-message-keys` + +If there is currently no GitHub issue open for your proposed contribution, +then please make one. This allows us to assign milestones and triage priority. + +### 3. Install the project dependencies. + +`$ npm install` + +### 4. Develop your feature + +Commit as often as you like. Your branch will be squashed when the pull request is merged. + +### 5. Run the tests + +`$ npm run test` + +### 6. Run linting + +`$ npm run lint` + +### 7. Submit your pull request + +In the main comment of the pull request, you must state the GitHub issue that your PR +resolves. You do this by using the syntax `Resolves #`. An example of this +can be found [here](https://github.com/pebble/clay/pull/81) + + + +# Project Structure and Development + + +## Important Files + +There are two main entry points for Clay - `index.js` and `src/scripts/config-page.js`. + +### index.js + +This is the main entry point for the code that will run in the Pebble app's `src/js/app.js`. +It is responsible for serializing the provided config into a data URI that will be opened +using `Pebble.openURL()`. It also persists data to `localStorage`. + +### src/scripts/config-page.js + +This is the main entry point for the code that runs on the generated config page, +and is responsible for passing the injected config and other components to the +`ClayConfig` class. + + +## Building + +Use the following command to build Clay during development. + +`$ npm run dev` + +This command packages up `src/scripts/config-page.js` and `dev/dev.js` into the `tmp/` directory +so `dev/dev.html` can include them as script tags. This will also watch for changes +in the project. + +While developing components and other functionality for Clay, it is much easier to +work with the files in the `dev/` directory than on a phone or emulator. Below is +an explanation of the files and their purpose. + +| File | Purpose | +|----------|-----| +| `dev.html` | Open this page in a browser after running `$ npm run dev`. | +| `dev.js` | Injects the components and dependencies into the window the same way `index.js` would. | +| `config.js` | Clay config to use as a sandbox for testing components. | +| `custom-fn.js` | Clay custom function to be injected by `dev.js`. | +| `emulator.html` | Copy of the HTML page that is used to make the Clay compatible with the Pebble SDK emulator. | +| `uri-test.html` | Used to stress test URI creation for older browser versions. | + + +## Testing your change inside of a test project. + +Once your change is ready to be tested in the emulator or on the watch, follow these steps: + +1. From your Clay fork run `$ npm run pebble-build`. This builds Clay to work with the Pebble SDK +2. From your test Pebble project, run `$ pebble package install /path/to/your/clay/fork`. + This will modify your `package.json` to point directly to your local copy of Clay. +3. Run the usual`$ pebble build && pebble install --emulator basalt && pebble emu-app-config` to test your modifications +4. If you make modifications to your fork of Clay, you must repeat the above steps. + + +## Functionality + +Most of the magic happens in the `src/scripts/lib` directory. `config-page.js` +initializes a new instance of `ClayConfig` and calls the injected custom function +(`window.customFn`) with the `ClayConfig` as its context. This allows developers to +add extra functionality to the config page, such as setting values of items dynamically +or registering small custom components. + +Once the `ClayConfig` is initialized, we run the `.build()` method. This iterates over +the config and injects each item into the page. Each item is an instance of `ClayItem`. +It also indexes the items to later be retrieved with `.getAllItems()`, +`.getItemByMessageKey()`, `.getItemById()`, `.getItemsByType()`. + + +## Testing + +Clay enforces 100% test coverage. Chances are, that if you are submitting a pull request, +there should be tests for the proposed code changes. Have a look at the other tests in +the repository to see some examples of how you should be writing your tests. + +There are two commands to use while writing your tests. + + - `$ npm run test` - Runs all tests once. + - `$ npm run test-debug` - Watches for file changes and re-runs all tests when it + detects a change. This also leaves an in instance of Google Chrome running. + If you click the "Debug" button in the top right of the page, a new tab will open. + You can then use the Google Chrome developer tools to debug your tests as they run. + Refreshing the page will re-run the tests. + +## Style Guide + +Our style guide is very similar to the +[Airbnb style guide.](https://github.com/airbnb/javascript/tree/master/es5) with the +following exceptions: + + - When saving a reference to `this` use `self`. + ```javascript + // bad + function() { + var _this = this; + return function() { + console.log(_this); + }; + } + + // bad + function() { + var that = this; + return function() { + console.log(that); + }; + } + + // good + function() { + var self = this; + return function() { + console.log(self); + }; + } + ``` + - Don't double name your functions. It makes refactoring more difficult. + + ```javascript + // bad + var log = function log(msg) { + console.log(msg); + }; + + // good + var log = function(msg) { + console.log(msg); + }; + ``` + +The style guide is enforced using ESLint. Run `$ npm run lint` to ensure you are +adhering to the style guide. + +## Getting Help + + - Chat to us in the `#clay` channel on slack. http://slack.pbldev.io/ + - Visit the [Pebble Forums](https://forums.pebble.com/) + - Tweet at [@pebbledev](https://twitter.com/pebbledev) + - More options at https://developer.pebble.com/community/online/ diff --git a/README.md b/README.md index c6a2f8c..06029b4 100755 --- a/README.md +++ b/README.md @@ -5,6 +5,8 @@ Clay will by default automatically handle the 'showConfiguration' and 'webviewcl Clay is distributed as a [Pebble package](https://developer.pebble.com/guides/pebble-packages/) so it is super easy to include in your project. If you are upgrading from v0.1.x of Clay you need to follow the [migration guide](#migrating-from-v01x-to-v1x) before you can get started. +If you would like to contribute to Clay, check out the [contributing guide.](CONTRIBUTING.md) + # Getting Started (SDK 3.13 or higher) 1. Run `pebble package install pebble-clay` to install the package in your project @@ -1125,56 +1127,6 @@ clay.registerComponent(require('./my-custom-component')); - `_.template()` - `_.isObject()` -# Project Structure and Development - -There are two main entry points for Clay - `index.js` and `src/scripts/config-page.js`. - -#### index.js - -This is the main entry point for the code that will run in the Pebble app's `src/js/app.js`. It is responsible for serializing the provided config into a data URI that will be opened using `Pebble.openURL()`. It also persists data to `localStorage`. - -#### src/scripts/config-page.js - -This is the main entry point for the code that runs on the generated config page, and is responsible for passing the injected config and other components to the `ClayConfig` class. - - -### Building - -There are two ways to build Clay, production mode and development mode. - -#### Production Mode - -``` -$ npm run build -``` - -Packages up the entire Clay project into `dist/clay.js` to be required in the developer's `app.js`. - -#### Development Mode - -``` -$ npm run dev -``` - -Packages up `src/scripts/config-page.js` and `dev/dev.js` into the `tmp/` directory so `dev/dev.html` can include them as script tags. This will also watch for changes in the project. - -While developing components and other functionality for Clay, it is much easier to work with the files in the `dev/` directory than on a phone or emulator. Below is an explanation of the files and their purpose. - -| File | Purpose | -|----------|-----| -| `dev.html` | Open this page in a browser after running `$ npm run dev`. | -| `dev.js` | Injects the components and dependencies into the window the same way `index.js` would. | -| `config.js` | Clay config to use as a sandbox for testing components. | -| `custom-fn.js` | Clay custom function to be injected by `dev.js`. | -| `emulator.html` | Copy of the HTML page that is used to make the Clay compatible with the Pebble SDK emulator. | -| `uri-test.html` | Used to stress test URI creation for older browser versions. | - -## Functionality - -Most of the magic happens in the `src/scripts/lib` directory. `config-page.js` initializes a new instance of `ClayConfig` and calls the injected custom function (`window.customFn`) with the `ClayConfig` as its context. This allows developers to add extra functionality to the config page, such as setting values of items dynamically or registering small custom components. - -Once the `ClayConfig` is initialized, we run the `.build()` method. This iterates over the config and injects each item into the page. Each item is an instance of `ClayItem`. It also indexes the items to later be retrieved with `.getAllItems()`, `.getItemByMessageKey()`, `.getItemById()`, `.getItemsByType()`. - # Migrating from v0.1.x to v1.x There were some changes in the 3.13 SDK that required Clay to undergo some major changes. For the majority of developers a simple find and replace over your config will do the trick.