From 02471e1f619a8aad7b0888d46272134d22a75cd7 Mon Sep 17 00:00:00 2001 From: Robin van Baalen Date: Fri, 27 Mar 2015 14:05:41 -0400 Subject: [PATCH] chore(docs): update README.md Restructured README, added references to new Wiki pages and updated content Closes #3453 --- README.md | 216 +++++++++++++----------------------------------------- 1 file changed, 51 insertions(+), 165 deletions(-) diff --git a/README.md b/README.md index 7ca2336027..1e3bc2d982 100644 --- a/README.md +++ b/README.md @@ -1,61 +1,64 @@ -# bootstrap - [AngularJS](http://angularjs.org/) directives specific to [Bootstrap](http://getbootstrap.com) +# UI Bootstrap - [AngularJS](http://angularjs.org/) directives specific to [Bootstrap](http://getbootstrap.com) [![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/angular-ui/bootstrap?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) - -*** - [![Build Status](https://secure.travis-ci.org/angular-ui/bootstrap.svg)](http://travis-ci.org/angular-ui/bootstrap) [![devDependency Status](https://david-dm.org/angular-ui/bootstrap/dev-status.svg?branch=master)](https://david-dm.org/angular-ui/bootstrap#info=devDependencies) -## IMPT - 2015 PLANS AND ANGULAR 1.3 SUPPORT +### Quick links +- [Demo](#demo) +- [Installation](#installation) + - [Bower](#Install with Bower) + - [NuGet](#Install with NuGet) + - [Custom](#Custom build) + - [Manual](#Manual download) +- [Support](#support) + - [FAQ](#faq) + - [Supported browsers](#supported-browsers) + - [Need help?](#need-help) + - [Found a bug?](#found-a-bug) +- [Contributing to the project](#contributing-to-the-project) +- [Development, meeting minutes, roadmap and more.](#development-meeting-minutes-roadmap-and-more) + -As of 17 Jan 2015 the project has brought on new maintainers to try and clear through the backlog of Angular 1.3 issues. As you can appreciate this is a **massive** undertaking -by a purely part-time, unpaid volunteer team; so please be patient with us! The milestones are as follows: +# Demo -* **DONE** - The **0.12.1** milestone will be for bug fixes for the existing Angular 1.2 supported version -* The **0.13.0** milestone will contain issues / PRs that are majorly blocking 1.3 compatibility -* The **0.13.x** milestone will contain issues / PRs that are nice to haves for 1.3 compatibility -* The **1.0** milestone is TBA -* The **Backlog** milestone is nice to haves -* The **Purgatory** Milestone is *"Good luck getting that in"* +Do you want to see directives in action? Visit http://angular-ui.github.io/bootstrap/! -The plan is to: +# Installation -1. **DONE** - **Rapidly Release 0.12.1** - new Maintainers learning the merge and release process -1. **Triage of existing Pull Requests** - into 0.13.0, 0.13.x, Backlog and Purgatory milestones -1. **Triage of existing issues** - into 0.13.0, 0.13.x, Backlog and Purgatory milestones -1. Obligatory - **profit!** +Installation is easy as UI Bootstrap has minimal dependencies - only the AngularJS and Twitter Bootstrap's CSS are required. -## Demo +#### Install with Bower +```sh +$ bower install angular-ui-bootstrap +``` -Do you want to see directives in action? Visit http://angular-ui.github.io/bootstrap/! +#### Install with NuGet +To install AngularJS UI Bootstrap, run the following command in the Package Manager Console -## Installation +```sh +PM> Install-Package Angular.UI.Bootstrap +``` + +#### Custom build + +Head over to http://angular-ui.github.io/bootstrap/ and hit the *Custom build* button to create your own custom UI Bootstrap build, just the way you like it. -Installation is easy as angular-ui-bootstrap has minimal dependencies - only the AngularJS and Bootstrap's CSS are required. -After downloading dependencies (or better yet, referencing them from your favourite CDN) you need to download build version of this project. All the files and their purposes are described here: +#### Manual download + +After downloading dependencies (or better yet, referencing them from your favorite CDN) you need to download build version of this project. All the files and their purposes are described here: https://github.com/angular-ui/bootstrap/tree/gh-pages#build-files Don't worry, if you are not sure which file to take, opt for `ui-bootstrap-tpls-[version].min.js`. +### Adding dependency to your project + When you are done downloading all the dependencies and project files the only remaining part is to add dependencies on the `ui.bootstrap` AngularJS module: -```javascript +```js angular.module('myModule', ['ui.bootstrap']); ``` -Project files are also available through your favourite package manager: -* **Bower**: `bower install angular-bootstrap` -* **NuGet**: https://nuget.org/packages/Angular.UI.Bootstrap/ - -## Support - -If you are having problems making some directives work, there are several ways to get help: - -* Live help in the IRC (`#angularjs` channel at the `freenode` network). Use this [webchat](https://webchat.freenode.net/) or your own IRC client. -* Ask a question in [stackoverflow](http://stackoverflow.com/) under the [angular-ui-bootstrap](http://stackoverflow.com/questions/tagged/angular-ui-bootstrap) tag. -* Write your question in our [mailing list](https://groups.google.com/forum/#!categories/angular-ui/bootstrap). - -Project's issue on GitHub should be used discuss bugs and features. +# Support ## FAQ @@ -72,143 +75,26 @@ Directives from this repository are automatically tested with the following brow Modern mobile browsers should work without problems. -**IE 8 is not officially supported at the moment**. This project is run by volunteers and with the current number of commiters -we are not in the position to guarantee IE8 support. If you need support for IE8 we would welcome a contributor who would like to take care about IE8. -Alternatively you could sponsor this project to guarantee IE8 support. - -We believe that most of the directives would work OK after: -* including relevant shims (for ES5 we recommend https://github.com/kriskowal/es5-shim) -* taking care of the steps described in http://docs.angularjs.org/guide/ie - -We are simply not regularly testing against IE8. - -## Project philosophy - -### Native, lightweight directives - -We are aiming at providing a set of AngularJS directives based on Bootstrap's markup and CSS. The goal is to provide **native AngularJS directives** without any dependency on jQuery or Bootstrap's JavaScript. -It is often better to rewrite an existing JavaScript code and create a new, pure AngularJS directive. Most of the time the resulting directive is smaller as compared to the original JavaScript code size and better integrated into the AngularJS ecosystem. - -### Customizability - -All the directives in this repository should have their markup externalized as templates (loaded via `templateUrl`). In practice it means that you can **customize directive's markup at will**. One could even imagine providing a non-Bootstrap version of the templates! -### Take what you need and not more - -Each directive has its own AngularJS module without any dependencies on other modules or third-party JavaScript code. In practice it means that you can **just grab the code for the directives you need** and you are not obliged to drag the whole repository. - -### Quality and stability - -Directives should work. All the time and in all browsers. This is why all the directives have a comprehensive suite of unit tests. All the automated tests are executed on each checkin in several browsers: Chrome, ChromeCanary, Firefox, Opera, Safari, IE9. -In fact we are fortunate enough to **benefit from the same testing infrastructure as AngularJS**! - -## Support - -If you are having problems making some directives work, there are several ways to get help: +## Need help? +Need help using UI Bootstrap? * Live help in the IRC (`#angularjs` channel at the `freenode` network). Use this [webchat](https://webchat.freenode.net/) or your own IRC client. -* Ask a question in [stackoverflow](http://stackoverflow.com/) under the [angular-ui-bootstrap](http://stackoverflow.com/questions/tagged/angular-ui-bootstrap) tag. -* Write your question in our [mailing list](https://groups.google.com/forum/#!categories/angular-ui/bootstrap). - -Project's issue on GitHub should be used discuss bugs and features. +* Ask a question in [StackOverflow](http://stackoverflow.com/) under the [angular-ui-bootstrap](http://stackoverflow.com/questions/tagged/angular-ui-bootstrap) tag. -## Contributing to the project +**Please do not create new issues in this repository to ask questions about using UI Bootstrap** -We are always looking for the quality contributions! Please check the [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution guidelines. - -### Development -#### Prepare your environment -* Install [Node.js](http://nodejs.org/) and NPM (should come with) -* Install global dev dependencies: `npm install -g grunt-cli karma` -* Install local dev dependencies: `npm install` while current directory is bootstrap repo - -#### Build -* Build the whole project: `grunt` - this will run `lint`, `test`, and `concat` targets -* To build modules, first run `grunt html2js` then `grunt build:module1:module2...:moduleN` - -You can generate a custom build, containing only needed modules, from the project's homepage. -Alternatively you can run local Grunt build from the command line and list needed modules as shown below: - -```javascript -grunt build:modal:tabs:alert:popover:dropdownToggle:buttons:progressbar -``` +## Found a bug? +Please take a look at [CONTRIBUTING.md](CONTRIBUTING.md#you-think-youve-found-a-bug) and submit your issue [here](https://github.com/angular-ui/bootstrap/issues/new). -Check the Grunt build file for other tasks that are defined for this project. -#### TDD -* Run test: `grunt watch` - -This will start Karma server and will continuously watch files in the project, executing tests upon every change. +---- -#### Test coverage -Add the `--coverage` option (e.g. `grunt test --coverage`, `grunt watch --coverage`) to see reports on the test coverage. These coverage reports are found in the coverage folder. -### Customize templates +# Contributing to the project -As mentioned directives from this repository have all the markup externalized in templates. You might want to customize default -templates to match your desired look & feel, add new functionality etc. - -The easiest way to override an individual template is to use the ` -``` - -If you want to override more templates it makes sense to store them as individual files and feed the `$templateCache` from those partials. -For people using Grunt as the build tool it can be easily done using the `grunt-html2js` plugin. You can also configure your own template url. -Let's have a look: - -Your own template url is `views/partials/ui-bootstrap-tpls/alert/alert.html`. - -Add "html2js" task to your Gruntfile -```javascript -html2js: { - options: { - base: '.', - module: 'ui-templates', - rename: function (modulePath) { - var moduleName = modulePath.replace('app/views/partials/ui-bootstrap-tpls/', ''); - return 'template/' + moduleName; - } - }, - main: { - src: ['app/views/partials/ui-bootstrap-tpls/**/*.html'], - dest: '.tmp/ui-templates.js' - } -} -``` - -Make sure to load your template.js file -`` - -Inject the `ui-templates` module in your `app.js` -```javascript -angular.module('myApp', [ - 'ui.bootstrap', - 'ui-templates' -]); -``` - -Then it will work fine! - -For more information visit: https://github.com/karlgoldstein/grunt-html2js +We are always looking for the quality contributions! Please check the [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution guidelines. -### Release -* Bump up version number in `package.json` -* Commit the version change with the following message: `chore(release): [version number]` -* tag -* push changes and a tag (`git push --tags`) -* switch to the `gh-pages` branch: `git checkout gh-pages` -* copy content of the dist folder to the main folder -* Commit the version change with the following message: `chore(release): [version number]` -* push changes -* switch back to the `main branch` and modify `package.json` to bump up version for the next iteration -* commit (`chore(release): starting [version number]`) and push -* publish Bower and NuGet packages +# Development, meeting minutes, roadmap and more. -Well done! (If you don't like repeating yourself open a PR with a grunt task taking care of the above!) +Head over to the [Wiki](https://github.com/angular-ui/bootstrap/wiki) for notes on development for UI Bootstrap, meeting minutes from the UI Bootstrap team, roadmap plans, project philosophy and more.