Skip to content

Latest commit

 

History

History
104 lines (77 loc) · 4.6 KB

CONTRIBUTING.md

File metadata and controls

104 lines (77 loc) · 4.6 KB

Contributing

Let's improve Strand together! We're looking forward to receiving pull requests.

Developer Setup

Setting up the development environment is simple and easy.

Building the components

  1. Fork Strand
  2. Clone your fork (we'll refer to your fork as origin hereafter)
  3. Install the Node Package Manager dependencies
  4. Install the Bower dependencies
  5. Execute a Gulp build -- which is the default task
  6. Run the Gulp live task to serve the project resources locally, and automatically update when files are changed
$ git clone [email protected]:[my-user-name]/strand.git
$ cd strand/
$ npm install
$ bower install
$ gulp
$ gulp live

When using the server provided by gulp live, the Strand preview page can be accessed at http://localhost:8000/

Building the documentation

After building the components themselves, the documentation pages for Strand can be built by running the docs Gulp task:

$ gulp docs
$ gulp live:docs

When using the server provided by gulp live, the Strand documentation can be accessed at http://localhost:8001

Found an Issue?

If you find a bug in the source code or a mistake in the documentation, help us by submitting an issue.

If you have a solution, you can submit a Pull Request with the fix, but please log the issue anyway for tracking purposes.

Consideration of Submissions

If you are submitting a new component, or making significant architectural changes in your PR, please consider opening a spec-bug first for discussion purposes prior to comitting to the work. Generally our components are designed with the following philosophy:

  • Heavily leverage existing strand behaviors/patterns where applicable
  • Be data/API agnostic. All data sources should work for simple JS object/array patterns as well as when hooked up to sync or other pageable api adapters by exposing an index
  • Favor UI components. Generally speaking data considerations should be local to your application as they can vary wildly in use case and the library should remain as agnostic as possible.

Submitting a Pull Request

Before you submit your pull request consider the following guidelines:

  • Search GitHub for an open or closed Pull Request that relates to your submission.

  • When submitting a component, please limit your submission to 1 component or behavior per PR unless there is a parent -> child relationship between the components.

  • Make sure your fork is synched

  • Create a new branch from develop

  • Make your changes in a new git branch:

    git checkout -b my-branch-name

  • Create your patch

  • Follow our Coding Guidelines.

  • Commit your changes using a descriptive commit message

  • Push your branch to GitHub:

    git push origin my-branch-name

  • In GitHub, send a pull request to strand:develop.

  • If we suggest changes then:

    • Make the required updates
    • Rebase your branch and force push to your GitHub repository (this will update your Pull Request):
    git fetch upstream
git rebase -i upstream/develop
git push -f origin my-branch-name

  • When you solution is approved, please squash your commits

Thanks for your contribution!

After your pull request is merged

After your pull request is merged, you can safely delete your branch and pull the changes from the main (upstream) repository.

Coding Guidelines

To ensure consistency throughout the source code, keep these rules in mind as you are working:

  • All features or bug fixes must be tested
  • All public API methods must be documented in the doc.json included in the mm-element-name folder, as we use these to generate documentation
  • Regarding code styling in general:
    • Strand does not subscribe to a specific javascript code guideline, but readability and organization are paramount
    • Methods and properties should be named in a meaningful way
    • Please refer to any of the Strand components or shared javascript files for reference
    • Use of eval or innerHTML in components is strongly discouraged
    • Please use _name for variables and methods that should not be publicly accessible. This follows the general Polymer convention.