Skip to content
Newer
Older
100644 175 lines (110 sloc) 7.22 KB
fe3d0b9 @paulirish readme updates
paulirish authored
1 # Welcome, Friend!
2
325ebaa @addyosmani Some more readme tweaks.
addyosmani authored
3 ## What am I?
4
5 Yeoman is a robust and opinionated client-side stack, comprised of tools and frameworks that can help developers quickly build beautiful web applications. We take care of providing everything needed to get started without any of the normal headaches associated with a manual setup.
6
7 Yeoman is fast, performant and is optimized to work best in modern browsers.
8
d063611 @sindresorhus Improve readme
sindresorhus authored
9 For more information about the project, see [yeoman.io](http://yeoman.io).
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
10
c14bcac @sindresorhus Add mention about code style and fix indention of code blocks
sindresorhus authored
11
f565bca @addyosmani Updating references to docs, tweaking.
addyosmani authored
12 ## Installing (pre-launch)
fe3d0b9 @paulirish readme updates
paulirish authored
13
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
14 * Clone this repo and `cd` into it
d063611 @sindresorhus Improve readme
sindresorhus authored
15 * Run this command: `./setup/install.sh`
6efe9c8 @sindresorhus Update install instructions
sindresorhus authored
16 * `cd` into the `/cli` directory and run `sudo npm link`
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
17 * Navigate to a new directory and run `yeoman init` to make sure everything is working as expected.
450e42c @paulirish adding rvm to install dependencies. cleanup of readme. Install is eas…
paulirish authored
18
05e6312 @mattbanks make sure people run npm link after a git pull when updating
mattbanks authored
19 You can keep Yeoman up to date by using `git pull --rebase upstream master && cd cli && npm link`.
6efe9c8 @sindresorhus Update install instructions
sindresorhus authored
20
21 **Make sure to pull in the latest and test before filing an issue, it might be fixed already**
22
fe3d0b9 @paulirish readme updates
paulirish authored
23
f1f903c @addyosmani Adding usage examples and listing of commands for contributors. This …
addyosmani authored
24 ## Documentation
25
26 Yeoman supports a powerful set of high-level commands. These include:
27
8f98e17 @paulirish more syntax highlighting
paulirish authored
28 ```shell
f1f903c @addyosmani Adding usage examples and listing of commands for contributors. This …
addyosmani authored
29 yeoman init # Initialize and scaffold a new project using generator templates
30 yeoman build # Build an optimized version of your app, ready to deploy
31 yeoman server # Launch a preview server which will begin watching for changes
c269e4c @paulmillr Update refs to mocha.
paulmillr authored
32 yeoman test # Run a Mocha test harness in a headless Phantom.js
f1f903c @addyosmani Adding usage examples and listing of commands for contributors. This …
addyosmani authored
33
b77cd39 @sindresorhus Cleanup readme
sindresorhus authored
34 yeoman install # Install a package from the client-side package registry
f1f903c @addyosmani Adding usage examples and listing of commands for contributors. This …
addyosmani authored
35 yeoman uninstall # Uninstall the package
36 yeoman update # Update a package to the latest version
37 yeoman list # List the packages currently installed
38 yeoman search # Query the registry for matching package names
b77cd39 @sindresorhus Cleanup readme
sindresorhus authored
39 yeoman lookup # Look up info on a particular package
f1f903c @addyosmani Adding usage examples and listing of commands for contributors. This …
addyosmani authored
40
41 ```
42
43 A common initial workflow with Yeoman might be:
44
8f98e17 @paulirish more syntax highlighting
paulirish authored
45 ```shell
b77cd39 @sindresorhus Cleanup readme
sindresorhus authored
46 yeoman init # Invoke the most basic application scaffold (Bootstrap, Boilerplate etc.)
1a7395b @addyosmani Fixes #233 - updates references to build and intermediate dirs
addyosmani authored
47 yeoman build # Build your project, creating an optimized version in a new `dist` directory
48 yeoman server # Fire off a file watch/server process which also places an
49 # intermediate build of your project in `temp`
f1f903c @addyosmani Adding usage examples and listing of commands for contributors. This …
addyosmani authored
50
51 ```
52
53 Some more examples of how to use our commands include:
54
8f98e17 @paulirish more syntax highlighting
paulirish authored
55 ```shell
1a7395b @addyosmani Fixes #233 - updates references to build and intermediate dirs
addyosmani authored
56 # Generators for MVC/MV* Frameworks
1138522 @addyosmani Docs for #227
addyosmani authored
57 yeoman init angular # Invoke the AngularJS generator scaffold
b77cd39 @sindresorhus Cleanup readme
sindresorhus authored
58 yeoman init angular:controller # Invoke the AngularJS Controller sub-generator
1138522 @addyosmani Docs for #227
addyosmani authored
59 yeoman init bbb # Invoke the Backbone Boilerplate generator scaffold
1a7395b @addyosmani Fixes #233 - updates references to build and intermediate dirs
addyosmani authored
60 yeoman init ember # Invoke the Ember generator scaffold
61
62 # Generator for Chrome Apps
63 yeoman init chromeapps
64
65 # Package management
66 yeoman search jquery # Lookup jQuery in the Bower registry
b77cd39 @sindresorhus Cleanup readme
sindresorhus authored
67 yeoman install jquery underscore [depName] # Install a dependency or dependencies
68 yeoman update jquery # Update a specific dependency (e.g jquery)
f1f903c @addyosmani Adding usage examples and listing of commands for contributors. This …
addyosmani authored
69 ```
70
71
f565bca @addyosmani Updating references to docs, tweaking.
addyosmani authored
72 See the [complete documentation](https://github.com/yeoman/yeoman/tree/master/docs/cli) for more. We also have [extended documentation](https://github.com/mklabs/yeoman/wiki/_pages) available for those more interested in the Yeoman internals.
f1f903c @addyosmani Adding usage examples and listing of commands for contributors. This …
addyosmani authored
73
74
75
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
76 ### Trouble-shooting
77
78 If for any reason you experience exceptions after the yeoman installation process above, you may find the
79 following steps resolve these issues:
80
8f98e17 @paulirish more syntax highlighting
paulirish authored
81 ```shell
82 cd yeoman/cli
83 sudo -s 'npm install -g && npm link'
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
84 ```
fe3d0b9 @paulirish readme updates
paulirish authored
85
6b91fef @addyosmani Adding tweaks to contribution guide, disclaimer for private beta testers
addyosmani authored
86 Please also note that (pre-launch) commands such as `yeoman install`, `yeoman update` and `yeoman search` etc (i.e package management commands) will only work if you have [Bower](http://github.com/twitter/bower) installed. As this is also currently in private beta, please let us know if you need access and we'll sort that out.
eb655aa @addyosmani Adding note about bower access.
addyosmani authored
87
f565bca @addyosmani Updating references to docs, tweaking.
addyosmani authored
88 Should you run into any further problems beyond this, please open a [new issue](https://github.com/yeoman/yeoman/issues/new) and one of the team will be happy to follow up with you.
89
c14bcac @sindresorhus Add mention about code style and fix indention of code blocks
sindresorhus authored
90
325ebaa @addyosmani Some more readme tweaks.
addyosmani authored
91
59c0d7f @addyosmani Adding browser support to README.
addyosmani authored
92 ## Browser Support
93
d063611 @sindresorhus Improve readme
sindresorhus authored
94 * Modern browsers (latest version of Chrome, Safari, Firefox, Opera and IE10)
59c0d7f @addyosmani Adding browser support to README.
addyosmani authored
95 * Chrome on Android
96 * Mobile Safari
97
c14bcac @sindresorhus Add mention about code style and fix indention of code blocks
sindresorhus authored
98
8911835 @addyosmani Fixes #127 - improves credits in readme
addyosmani authored
99 ## Platform Support
100
6b91fef @addyosmani Adding tweaks to contribution guide, disclaimer for private beta testers
addyosmani authored
101 Yeoman 1.0 will support OS X and Linux. We will be aiming to bring in support for Windows in a future version of the project.
8911835 @addyosmani Fixes #127 - improves credits in readme
addyosmani authored
102
c14bcac @sindresorhus Add mention about code style and fix indention of code blocks
sindresorhus authored
103 ## Contribute
104
6b91fef @addyosmani Adding tweaks to contribution guide, disclaimer for private beta testers
addyosmani authored
105 We are more than happy to accept external contributions to the project in the form of feedback, bug reports and even better - pull requests :) At this time we are primarily focusing on improving the user-experience and stability of Yeoman for our first release. Please keep this in mind if submitting feature requests, which we're happy to consider for future versions.
106
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
107 ### Repos
108
109 * [Yeoman (CLI, Insights)](http://github.com/yeoman/yeoman)
110 * [Yeoman I/O Holding Page](http://github.com/yeoman/yeoman.io)
d063611 @sindresorhus Improve readme
sindresorhus authored
111 * [Yeoman I/O Site](http://github.com/yeoman/yeoman.io) (site branch)
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
112
c14bcac @sindresorhus Add mention about code style and fix indention of code blocks
sindresorhus authored
113 ### Style Guide
114
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
115 This project follows the [jQuery Style Guide](http://docs.jquery.com/JQuery_Core_Style_Guidelines) with an exception of two space indentation and multiple var statements. Please ensure any pull requests follow this closely. If you notice existing code which doesn't follow these practices, feel free to shout and we will address this.
116
b9fe2e5 @sindresorhus Make the CLI code pass JSHint
sindresorhus authored
117 ### Pull Request Guidelines
118
119 - Lint the code by running `grunt` in the `/cli` folder before submitting a pull request
120 - Develop in a topic branch, not master
121
987517f @paulirish update readme with testing info.
paulirish authored
122 ### Tests
123
124 Yeoman has a test suite to ensure it's reliably and accurately working as a developer tool. You can find the main test suite in [`test/test-build.js`](https://github.com/yeoman/yeoman/blob/master/cli/test/test-build.js), most of the assertions are [checks against yeoman cli stdout](https://github.com/mklabs/yeoman/wiki/test-build).
125
b4b6057 @paulirish readme update about testing
paulirish authored
126 To run our test suite:
127
128 ```sh
129 npm test
130 ```
131
b77cd39 @sindresorhus Cleanup readme
sindresorhus authored
132 Do note that if any CLI prompts are not accounted for the test suite will have a timeout failure.
b4b6057 @paulirish readme update about testing
paulirish authored
133
d6c85b5 @paulirish add to readme about our existing developer documentation.
paulirish authored
134 ### Developer Docs
135
b77cd39 @sindresorhus Cleanup readme
sindresorhus authored
136 We have significant developer docs for you if you'd like to hack on Yeoman.
d6c85b5 @paulirish add to readme about our existing developer documentation.
paulirish authored
137
6b91fef @addyosmani Adding tweaks to contribution guide, disclaimer for private beta testers
addyosmani authored
138 Currently you can find much of the details on [mklabs' yeoman wiki](https://github.com/mklabs/yeoman/wiki/_pages) but also [our primary project](https://github.com/yeoman/yeoman/tree/master/docs/cli).
d6c85b5 @paulirish add to readme about our existing developer documentation.
paulirish authored
139
b77cd39 @sindresorhus Cleanup readme
sindresorhus authored
140 You're also welcome to `git blame` back to commit messages and pull requests. As a project we value comprehensive discussion for our fellow developers.
b9fe2e5 @sindresorhus Make the CLI code pass JSHint
sindresorhus authored
141
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
142 ## About
143
8911835 @addyosmani Fixes #127 - improves credits in readme
addyosmani authored
144 Yeoman is an open-source project by [Google](http://google.com) which builds on top of [Grunt](https://github.com/cowboy/grunt) and [node-build-script](http://github.com/h5bp/node-build-script). We utilize a number of useful open-source solutions including:
145
146 * Twitter Bootstrap
d063611 @sindresorhus Improve readme
sindresorhus authored
147 * HTML5 Boilerplate
8911835 @addyosmani Fixes #127 - improves credits in readme
addyosmani authored
148 * Modernizr
149 * Twitter Bower
d063611 @sindresorhus Improve readme
sindresorhus authored
150 * Node.js
8911835 @addyosmani Fixes #127 - improves credits in readme
addyosmani authored
151 * NPM
152 * Compass
d063611 @sindresorhus Improve readme
sindresorhus authored
153 * Socket.IO
154 * CoffeeScript
155 * Mocha
156 * Jasmine
8911835 @addyosmani Fixes #127 - improves credits in readme
addyosmani authored
157 * PhantomJS
d063611 @sindresorhus Improve readme
sindresorhus authored
158 * And [more...](https://github.com/yeoman/yeoman/wiki/Dependencies)
8911835 @addyosmani Fixes #127 - improves credits in readme
addyosmani authored
159
160 Version 1 of the project features the combined efforts of:
161
d063611 @sindresorhus Improve readme
sindresorhus authored
162 * [Paul Irish](http://paulirish.com)
8911835 @addyosmani Fixes #127 - improves credits in readme
addyosmani authored
163 * [Addy Osmani](http://addyosmani.com)
d063611 @sindresorhus Improve readme
sindresorhus authored
164 * [Mickael Daniel](http://blog.mklog.fr)
165 * [Sindre Sorhus](http://sindresorhus.com)
8bc0352 @ebidel Update master
ebidel authored
166 * [Eric Bidelman](http://ericbidelman.com)
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
167
d063611 @sindresorhus Improve readme
sindresorhus authored
168 and other developers.
f64ffb8 @addyosmani Updating project readme with troubleshooting for install, links to re…
addyosmani authored
169
f565bca @addyosmani Updating references to docs, tweaking.
addyosmani authored
170 We will be aiming to officially release the project in Q3, 2012.
6b91fef @addyosmani Adding tweaks to contribution guide, disclaimer for private beta testers
addyosmani authored
171
172 ## Disclaimer
173
6efe9c8 @sindresorhus Update install instructions
sindresorhus authored
174 If you've been invited to try out the project as a beta tester or contributor, all we ask is that you refrain from publicly publishing/sharing the project sources until we have launched. This is to ensure that the first public version of Yeoman is as stable as possible, but would also stop unicorns from crying. Thanks for understanding :)
Something went wrong with that request. Please try again.