Merge pull request #138 from OpenF2/1.3.1-wip

F2 version 1.3.1

CONTRIBUTING.md

@@ -1,53 +1,68 @@
-# How to Contribute to F2
-
-F2 is an open and free web integration framework designed to help you and other financial industry participants develop custom solutions that combine the best tools and content from multiple providers into one, privately-labeled, seamlessly integrated front-end.
+# Contributing to F2
 
 F2 is currently maintained by [Markit On Demand](http://www.markitondemand.com) and you're encouraged to contribute to this project right here on GitHub. The following are guidelines for contributing; please familiarize yourself before sending pull requests.
 
+**Thank you to the [growing list of contributors](https://github.com/OpenF2/F2/graphs/contributors)!**
+
 ## Getting Started
 
-A couple of ground rules.
+First, a couple of ground rules.
 
-* Make sure you have a [GitHub account](https://github.com/signup/free).
-* [Submit a ticket for your issue](https://github.com/OpenF2/F2/issues), assuming one does not already exist. (Search first!)
+1. Make sure you have a [GitHub account](https://github.com/signup/free).
+2. [Submit a ticket for your issue](https://github.com/OpenF2/F2/issues), assuming one does not already exist. **(Search first!)**
 	* Clearly describe the issue including steps to reproduce when it is a bug.
-	* Be sure to include the F2 version number.
-* Fork the F2 repository on GitHub.
+	* Include the F2 version number.
+3. [Fork the F2 repository](https://github.com/OpenF2/F2/fork).
 
 ## Making Changes
 
-* Create a branch from where you want to base your changes.
-* Do not work directly in `master`; create a branch _based on_ `master` using `git checkout -b 'your_branch_name' master`.
-* Follow our [coding standards](https://github.com/OpenF2/F2/wiki/Coding-Standards).
-* Preferably add _and document_ unit test(s) for your changes. 
-* Re-run all the Jasmine tests to confirm your changes didn't break anything.
-* Perform browser testing in our [supported browsers](wiki/Browser-Compatibility).
-* Add a detailed commit message.
+### Understanding the "wip" branch
+
+The latest F2 changes can be found in the `-wip` branch. This branch's name uses the upcoming version number followed by `-wip` which stands for "work-in-progress", for example `1.3.1-wip` as shown below. There will only be one `-wip` branch at any given time.
+
+Do not work directly in `master`! 
+
+![Branches](http://docs.openf2.org/img/branches.png)
+
+### Steps
+
+Once you've forked the F2 repository:
+
+1. Create a new branch in your fork from the `next.version-wip` branch.  Do not work directly in `master`! 
+    * `$> git checkout -b 'your_branch_name' next.version-wip`
+3. Read the F2 [coding standards](https://github.com/OpenF2/F2/wiki/Coding-Standards).
+4. Add and document unit test(s) for your changes. At least one unit test is required.
+5. Re-run all the Jasmine tests to confirm your changes didn't break anything. `$> grunt test`
+6. Perform browser testing in [supported browsers](https://github.com/OpenF2/F2/wiki/Browser-Compatibility).
+7. Add a detailed commit message.
 
-## Submitting Changes
+### Committing Changes
 
+* You should only commit files you have changed. **Do not commit compiled or generated F2 files, except:**
+    * If you've modified any file in the `/sdk/src/` directory, you must commit `/sdk/f2.min.js` for the [Travis unit tests](https://travis-ci.org/OpenF2/F2).
 * Push committed changes to your branch.
-* [Submit a pull request](https://help.github.com/articles/using-pull-requests) in the F2 project repository.
+* [Submit a pull request](https://help.github.com/articles/using-pull-requests) for `F2\next.version-wip` **not `F2\master`**.
 * Add a message or additional detail for your changes in the pull request.
-* Wait for your change to be reviewed.
+* Wait for your change(s) to be reviewed.
 
 
 ## Coding Standards
 
-Coding standards promote a common vocabulary and syntax so that our fellow developers can concentrate on _what_ you're saying rather than on _how_ you're saying it. It is ultimately up to you how you write your own code, but please become familiar with the standards and use them when contributing back to F2.
+Coding standards promote a common vocabulary and syntax so that our fellow developers can concentrate on _what_ you're saying rather than on _how_ you're saying it. It is ultimately up to you how you write your own code, but please become familiar with the standards and use them when contributing to F2.
 
 Coding standards help an individual project, and also make it easier for one project to reuse components from another project. This, of course, is a core component of F2.
 
 Read our [coding standards](https://github.com/OpenF2/F2/wiki/Coding-Standards) on the wiki.
 
 ## Keep in Touch
 
-If you have any questions while writing code to contribute back to F2, contact us on our [Google Group](https://groups.google.com/forum/#!forum/OpenF2), find us on Twitter [@OpenF2](https://twitter.com/OpenF2) or by email at [info@openf2.org](mailto:info@openf2.org). You can also follow [our blog](http://blog.openf2.org) for more in-depth F2 updates.
+If you have any questions while writing code to contribute to F2, post a message on the [Google Group](https://groups.google.com/forum/#!forum/OpenF2), find us on Twitter [@OpenF2](https://twitter.com/OpenF2) or by email at [info@openf2.org](mailto:info@openf2.org). You can also follow [our blog](http://blog.openf2.org) for more in-depth F2 updates.
 
 ## Resources
 
 * [F2 Google Group](https://groups.google.com/forum/#!forum/OpenF2)
 * [F2 Coding Standards](https://github.com/OpenF2/F2/wiki/Coding-Standards)
 * [GitHub Documentation: Using Pull Requests](https://help.github.com/articles/using-pull-requests)
 * [GitHub Documentation](https://help.github.com/)
-* [Markit On Demand](http://www.markitondemand.com/)
+* [Markit On Demand](http://www.markitondemand.com/) or [@markitondemand](https://twitter.com/markitondemand)
+* Markit On Demand Labs - [@MOD/L](https://twitter.com/mod_labs)

README.md

@@ -2,102 +2,91 @@
 
 <img src="https://secure.gravatar.com/avatar/4a9321787652abeea63089c8fdf0face?s=125" align="right">
 
-F2 is an open and free web integration framework designed to help the financial services community develop custom solutions that combine the best tools and content from multiple parties into one, privately-labeled, seamlessly integrated front-end. The [essential components](http://docs.openf2.org/index.html#framework) core to the framework are containers, apps, context, and the Registry&mdash;all supported under the hood by **[F2.js](http://docs.openf2.org/f2js-sdk.html)**, a JavaScript SDK which provides an extensible foundation powering all F2-enabled web applications.
+F2 is an open and free web integration framework designed to help the financial services community develop custom web and mobile applications. These solutions can combine the best tools and content from multiple parties into one, privately-labeled, seamlessly integrated front-end.
 
-F2 is currently maintained by [Markit On Demand](http://www.markitondemand.com). Visit [OpenF2.org](http://www.openf2.org) for more information and follow [@OpenF2](http://twitter.com/OpenF2) on Twitter.
+F2 is currently maintained by [Markit On Demand](http://www.markitondemand.com). Visit [OpenF2.org](http://www.openf2.org) for more information, follow [@OpenF2](http://twitter.com/OpenF2) on Twitter and subscribe to the [F2 blog](http://blog.openf2.org).
 
-## Quick Start
+## Get Started
 
-Clone the repo, `git clone https://github.com/OpenF2/F2.git`, or [download the latest version](https://github.com/OpenF2/F2/zipball/master).
+Two core components of F2 are **containers** and **apps** which are stitched together by **F2.js**. Get started by browsing to the framework documentation at [**docs.openf2.org**](http://docs.openf2.org).
 
-Browse to the **Get Started** documentation for [containers](http://docs.openf2.org/container-development.html#get-started) or [apps](http://docs.openf2.org/app-development.html#get-started).
+## Developers [![Build Status](https://travis-ci.org/OpenF2/F2.png?branch=master)](https://travis-ci.org/OpenF2/F2)
 
-### Download F2.js
 
-* Development: [F2.debug.js](https://github.com/OpenF2/F2/blob/master/sdk/f2.debug.js)
-* Production: [F2.js](https://github.com/OpenF2/F2/blob/master/F2.latest.js) (34.3kb)
+### Get F2.js
 
+* Production: [F2.js](https://raw.github.com/OpenF2/F2/master/F2.latest.js) (34.3kb, minified and gzipped)
+* Development: [F2.debug.js](https://raw.github.com/OpenF2/F2/master/sdk/f2.debug.js)
+* [F2.js packages](http://docs.openf2.org/f2js-sdk.html#packages) are also available, including [F2.basic.js](https://raw.github.com/OpenF2/F2/master/sdk/packages/f2.basic.min.js) (7kb, minified and gzipped)
+* We have [CDN support](http://blog.openf2.org/2013/09/f2-now-on-cdnjs.html)&mdash;get F2.js and any packages [on cdnjs.com](http://cdnjs.com/libraries/F2/).
+* For .NET developers: install the [NuGet Package](https://nuget.org/packages/F2/).
 
-## Developers [![Build Status](https://travis-ci.org/OpenF2/F2.png?branch=master)](https://travis-ci.org/OpenF2/F2)
+### Get Examples
+
+Example containers and apps can be found in at least two places: [openf2.org/examples](http://www.openf2.org/examples) and in the [downloadable F2 examples](http://docs.openf2.org/F2-examples.zip) zip archive. There are also [numerous jsFiddles](http://docs.openf2.org/container-development.html#requesting-apps-on-demand) available in the documentation. This repository contains examples, too. 
 
-**Important**: If you just want to develop F2 containers or apps, you can skip the section below. _You do not need the command line, Node.js or Grunt to develop with F2_.
+* Clone this repository using `git clone git@github.com:OpenF2/F2.git`, or
+* Download the [latest version](https://github.com/OpenF2/F2/zipball/master) of this repository
 
-### Packages
+### Docs
 
-Packages are variants of F2.js. They are ideally used when, for example, a container already has jQuery or [sandboxed apps](http://docs.openf2.org/app-development.html#secure-apps) aren't needed. [Read more about F2 packages](http://docs.openf2.org/f2js-sdk.html#packages).
+We have robust documentation divided into three main sections:
 
-* Basic: 
-    * Development: [F2.basic.js](https://github.com/OpenF2/F2/blob/master/sdk/packages/f2.basic.js)
-    * Production: [F2.basic.min.js](https://github.com/OpenF2/F2/blob/master/sdk/packages/f2.basic.min.js) (7.6kb)
-* No easyXDM:
-    * Development: [f2.no-easyXDM.js](https://github.com/OpenF2/F2/blob/master/sdk/packages/f2.no-easyXDM.js)
-    * Production: [f2.no-easyXDM.min.js](https://github.com/OpenF2/F2/blob/master/sdk/packages/f2.no-easyXDM.min.js) (30.4kb)	    	    
-* No Bootstrap: 
-    * Development: [F2.no-bootstrap.js](https://github.com/OpenF2/F2/blob/master/sdk/packages/f2.no-bootstrap.js)
-    * Production: [F2.no-bootstrap.min.js](https://github.com/OpenF2/F2/blob/master/sdk/packages/f2.no-bootstrap.min.js) (33.6kb)
-* No jQuery, Bootstrap:
-    * Development: [f2.no-jquery-or-bootstrap.js](https://github.com/OpenF2/F2/blob/master/sdk/packages/f2.no-jquery-or-bootstrap.js) 
-    * Production: [f2.no-jquery-or-bootstrap.min.js](https://github.com/OpenF2/F2/blob/master/sdk/packages/f2.no-jquery-or-bootstrap.min.js) (11.5kb)
+* Understanding [the Basics](http://docs.openf2.org)
+* Developing [apps](http://docs.openf2.org/app-development.html),  [containers](http://docs.openf2.org/container-development.html), or [F2 plugins](http://docs.openf2.org/extending-f2.html).
+* [F2.js API](http://docs.openf2.org/sdk/classes/F2.html)
 
 
-### Build F2
+### Contribute to F2
+
+Join our team and help contribute to F2 on GitHub. Begin by reading our [contribution guidelines](CONTRIBUTING.md), and then start by [forking the repo](https://github.com/OpenF2/F2/fork), sending [pull requests](https://help.github.com/articles/using-pull-requests), or [submitting issues](https://github.com/OpenF2/F2/issues).
 
-For those [contributing to F2](CONTRIBUTING.md), you'll need to setup your dev environment. To configure it, be sure you have [Node.js](http://nodejs.org/) installed, then run the following command from the project root directory:
+**Thank you to the [growing list of contributors](https://github.com/OpenF2/F2/graphs/contributors)!**
+
+#### Setup
+
+Be sure you have cloned this repository and have [Node.js](http://nodejs.org/) installed, then run the following command from the project root directory:
 
 `$> npm install`
 
 This command will install the [Grunt CLI](http://gruntjs.com/getting-started#installing-the-cli) in addition to all dependencies needed to build F2. Depending on your configuration, you may need to be an admin to install some of these Node packages. Additionally, some packages may need to be [installed globally](http://blog.nodejs.org/2011/03/23/npm-1-0-global-vs-local-installation/) using the `-g` switch. If the installation fails due to directory permissions, use:
 
 `$> sudo npm install`
 
-We are using [markitdown](https://github.com/markitondemand/markitdown), a lightweight pandoc wrapper, for converting markdown files to HTML for the [F2 docs](http://docs.openf2.org). [Pandoc](http://johnmacfarlane.net/pandoc/index.html) is required for markitdown and there are [installation packages available](http://johnmacfarlane.net/pandoc/installing.html) for Windows and Mac OS.
+We are using [markitdown](https://github.com/markitondemand/markitdown), a lightweight pandoc wrapper, for converting markdown files to HTML for the [F2 docs](http://docs.openf2.org). **[Pandoc](http://johnmacfarlane.net/pandoc/index.html) is required** for markitdown and there are [installation packages available](http://johnmacfarlane.net/pandoc/installing.html) for Windows and Mac OS.
 
-To **build F2**, run:
+#### Build F2
+
+To compile F2.js and the accompanying docs, run:
 
 `$> grunt`
 
-For help and a list of available tasks, run:
+For help and a list of available grunt tasks, run:
 
 `$> grunt --help`
 
-_Some Mac users have run into a Grunt "cannot run in wd" error when using `grunt` and/or `npm install`. If you're getting that error in your shell, try using `--unsafe-perm` [as discussed here](https://github.com/isaacs/npm/issues/2984)._
-
 ### Versioning
 
 The latest version of F2.js will always be in `master` and the version number/release date is available on the command line by using:
 
 `$> grunt version`.
 
-In accordance with industry standards, F2 is currently maintained, in as far as reasonably possible, under the Semantic Versioning guidelines.
-
-Releases will be numbered with the following format:
+In accordance with industry standards, F2 is currently maintained, in as far as reasonably possible, under the Semantic Versioning guidelines. Releases will be numbered with the following format:
 
 `<major>.<minor>.<patch>`
 
 For more information on SemVer, please visit [SemVer.org](http://semver.org/).
 
-### Upgrading
+#### Upgrading
 
-It is our goal to make upgrading to the latest version of F2 a minor effort for development teams. For more notes on upgrading your container or app to the latest version of F2, [read more in the Docs](http://docs.openf2.org/f2js-sdk.html#upgrading).
+It is our goal to make upgrading to the latest version of F2 a minor effort for development teams. [Read more in the Docs](http://docs.openf2.org/f2js-sdk.html#upgrading).
 
 ### Issues, Enhancements, Bugs
 
-Have a question? Want to chat? Open an [Issue on GitHub](https://github.com/OpenF2/F2/issues), ask it on our [Google Group](https://groups.google.com/forum/#!forum/OpenF2) or send an email to <info@openf2.org>.
+Have a question? Find a bug? Open an [Issue on GitHub](https://github.com/OpenF2/F2/issues), post a topic on the [Google Group](https://groups.google.com/forum/#!forum/OpenF2) or send an email to <info@openf2.org>.
 
 To track bugs, issues and enhancement requests, we are using [Issues on GitHub](https://github.com/OpenF2/F2/issues).
 
-### NuGet Package
-
-Good news if you're using C#! We have an [F2 NuGet package available](https://nuget.org/packages/F2/). In your Package Manager Console run:
-
-`PM> Install-Package F2`
-
-### Collaboration 
-
-Join our team and help contribute to F2 on GitHub. Begin by reading our [contribution guidelines](CONTRIBUTING.md), and then start by [forking the repo](https://github.com/OpenF2/F2/fork), sending [pull requests](https://help.github.com/articles/using-pull-requests), or [submitting issues](https://github.com/OpenF2/F2/issues).
-
-Thank you to the [growing list of contributors](https://github.com/OpenF2/F2/graphs/contributors)!
-
 ## Copyright and License
 
 Copyright &copy; 2013 Markit On Demand, Inc.