RSpec-2 Documentation
July 1st, 2010
RSpec-2 is getting close to a release candidate, and as the beta gems have been flowing a lot of questions have been coming in, especially about documentation. Here is some information that should help.
Source code
RSpec development has moved to the rspec account on github. There are five repositories at the moment:
- http://github.com/rspec/rspec
- http://github.com/rspec/rspec-core
- http://github.com/rspec/rspec-expectations
- http://github.com/rspec/rspec-mocks
- http://github.com/rspec/rspec-rails
rspec-rails depends on rspec, which depends, in turn, on the other three.
This structure has many benefits, but one cost is that the documentation, though plentiful, is a bit scattered.
READMEs
- http://github.com/rspec/rspec
- http://github.com/rspec/rspec-core
- http://github.com/rspec/rspec-expectations
- http://github.com/rspec/rspec-mocks
- http://github.com/rspec/rspec-rails
Upgrade Notes
- http://github.com/rspec/rspec-core/blob/master/Upgrade.markdown
- http://github.com/rspec/rspec-expectations/blob/master/Upgrade.markdown
- http://github.com/rspec/rspec-rails/blob/master/Upgrade.markdown
Cucumber features
Each of the repos has a growing set of Cucumber features. Some of the features have been added in after the fact, but many of the new features have been driven out using Cucumber. These are a great source of “How-To” information, and you know they’re up to date because they are executable documentation.
If you peruse these and are unable to find the information you’re looking for, or find any of the information incomplete or confusing, please, please, please submit a github issue (see Known Issues, below). Or, better yet, submit a patch!
- http://github.com/rspec/rspec-core/tree/master/features/
- http://github.com/rspec/rspec-expectations/tree/master/features/
- http://github.com/rspec/rspec-mocks/tree/master/features/
- http://github.com/rspec/rspec-rails/tree/master/features/
RDoc
The RDoc is arguably the weakest link here. Patches welcome!
- http://rdoc.info/projects/rspec/rspec-core
- http://rdoc.info/projects/rspec/rspec-expectations
- http://rdoc.info/projects/rspec/rspec-mocks
- http://rdoc.info/projects/rspec/rspec-rails
Known Issues
Issues for rspec-2 are being maintained on github.
- http://github.com/rspec/rspec-core/issues
- http://github.com/rspec/rspec-expectations/issues
- http://github.com/rspec/rspec-mocks/issues
- http://github.com/rspec/rspec-rails/issues
If you want to submit an issue and you’re not sure which tracker it belongs in, just pick the one you think is most appropriate. I’m more interested in getting the feedback then you knowing where to put the issue. I’ll move it to the right place if necessary.
Wikis
PLEASE NOTE: github wikis can be updated by anybody with a github account, and I don’t get any notification when wiki pages have changed. Most of the time, users add valuable information, but the structure is poor and always in flux, and there have been occasions in which the information was either misleading or simply inaccurate. The Cucumber features mentioned above, though currently incomplete, are a much better source for accurate documentation.
- http://wiki.github.com/rspec/rspec/
- http://wiki.github.com/rspec/rspec-core/
- http://wiki.github.com/rspec/rspec-expectations/
- http://wiki.github.com/rspec/rspec-mocks/
- http://wiki.github.com/rspec/rspec-rails/
The RSpec Book
The RSpec Book is being updated for RSpec-2 and Rails-3. There will still be references back to RSpec-1 and Rails-2 where things have changed, but the focus will be on the way forward. Once the rails-3 and rspec-2 release candidates are out, we’ll release one more updated PDF of the book for those in the beta program, and then off to the printer it goes. FINALLY!
July 1st, 2010 at 1:02 pm
Can’t wait for the RSpec Book. I’ve been happily using RSpec 2 for a few weeks now, awesome work!
July 2nd, 2010 at 1:10 pm
david,
i use rspec every day as part of my development practice. it’s pretty much the most important piece of software i use.
i really appreciate the effort you’re putting into the next version.
anyway the point is: thank you very much.
July 3rd, 2010 at 1:56 pm
Thanks David for your hard hard work on this, and for updating the book for RSpec-2 and Rails-3 — it’s like we got 2 books in 1
July 7th, 2010 at 1:38 am
Thanks for the update David. I’ve had the book on pre-order through pragprog and have been referencing the beta pdf nearly every day. It’s great to know something I ordered months ago is still being refined and updated to the current technologies and not being released already outdated. It’s also great to finally have a recent rdoc for RSpec. I’m only a month or so into TDD and it’s been quite an adventure piecing together best practices from the github source and the old 1.x rdocs.
Thanks for all your hard work, - FJM
July 21st, 2010 at 12:01 am
I reference the Pragprog pdf Rspec Book - its a great job!
Now I’m trying my shirt for a Gem - and disecting other gems, copy/pasting and emulating them, I just cannot seem to get the right setup!
My (impertinent for which I apologise) question is: how do I get the Rails (world) into my gem without actually ‘rails new some_app’ - which then will bleed through to the gem cut? Do other gem cutters (git)ignore all the Rails folders in their gems prior to git init?
Puzzled and somewhat frustrated as I really would like to upload a gem with some good test coverage.
best regards, Walther
July 21st, 2010 at 7:19 pm
Well - I’ll keep this ‘thread’ alive single-handedly
As with so many things in life - if you leave them alone long enough, eventually they will go away: food, krugerrands on the pavement, girl friends,
Thanks for keeping this space open for me to make a total fool out of myself
/Walther
December 30th, 2010 at 6:28 am
its great thanks