mirror of
https://github.com/pebble-dev/clay.git
synced 2026-08-28 04:46:57 -04:00
#86/Added contribution instructions (#111)
* Added contribution instructions * remove production mode in the contributing guide. * Remove squashing commits from contributing guide * Add better examples for style guide. * Add getting help section * Change devsupport email to twitter * Add link to contributing guide from the main readme
This commit is contained in:
Keegan Lillo
+198
@@ -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.
|
||||
|
||||
`#<issue-id>/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 #<issue-id>`. 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/
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user