Not sure what do you mean, but docrails has been out of sync for a
while due to some issues in GitHub. They are sync'ed again.
In order to fix a guide as it is in master, just clone docrails, edit,
and push (docrails has public write access). To fix guides of previous
versions please send an ordinary pull request to rails, and bring it
to the attention of Vijay or me in it.
Another thing. Are the guides for different versions of Rails,
organized in some way? I don't see the pattern..
A release of Rails is composed of source code, a test suite, and
documentation. To find the guides of a given rails version, checkout
that version.
As we code fixes, fixes to the docs are public with the next release,
the online docs are not updated. They are the docs of the current
release (there are the edge docs though, those are updated right away
automatically).
Traditionally the documentation published in rubyonrails.org is the
one for the stable version. This changed a little bit with 3.0, since
a lot of people were still in Rails 2. That's why you can browser
v2.3.8.
But that's just a symlink in the docs server made for convenience. We
perfectly may go back to just stable docs online. In any case, a rails
app has rake tasks to generate the API and guides for the Rails
version it is running on.
Ruby on Rails has two sets of official documentation: The Rails Guides
are for learning, and the Rails API is a reference.
They are part of the project, in particular they belong to the project
tree. The API is intermixed with code because it uses RDoc. The guides
have their own stuff below railties/guides. It is a custom set of
.textile source files together with some hand-crafted generators.
Thus, everything lives inside the rails git repository.
When a major release is coming, master is branched. For example, a
while back master was branched to 3-1-stable. In particular the docs
are branched together with everything. So we have now master,
3-1-stable, 3-0-stable, and 2-3-stable. And they have their
corresponding evolution.
The maintenance of the documentation, guides and API, happens in
master. Patches are expected to come with tests and docs coverage. In
particular, if a patch changes something in a guide, it should update
it. A new feature should be explained etc. Thus, the evolution of the
code, its tests, and its docs, go together. (In reality this is not
that perfect, but that's the way it should be.)
docrails exist as a easier way to accept doc patches for master,
bypassing the pull request process. And the changes committed to
docrails are all merged with rails master periodically.
If you want to contribute doc patches to other branches, you must send
in pull requests to Rails. The updates to the guides will happen when
there is a release of that particular branch. For eg. any changes to
3-0-stable will be published if and when the next version 3.0.11 comes
out.
As far as changes in the 2.3.x guides are concerned, I'm not sure if
there will be a 2.3.x release (except for security reasons) in the
future.
I think I do - but now I'm confused as to why there is a docrails
project. As all docs seem to be in the Rails project.
Yes that's a normal confusion. docrails it's not really a project, it
is only a convenience branch. Let me explain.
Rails has NO documentation project. Rails has NO testing team. Tests
and docs and code go together. They are/should be maintained as one.
In the old days, all contributions to Ruby on Rails went through a
ticketing system. That's now the combo GitHub issues/pull requests.
That's a good deal of work for the core team to manage, so docrails
was created as a way to patch the docs bypassing the ticketing system.
For example, you're reading the API and realize some example code is
malformed. Instead of sending a pull request, you can clone docrails
and push the change yourself.
docrails and rails master are cross-merged periodically.
Note that patches are still reviewed. But while in a ticket you
propose something and wait for the resolution. In a doc patch by
default the fix goes, only a later screening process may edit or
revert.
I guess this means that if I contribute to the 2.3 stable branch guide
on ActiveRecord, it will probably be a while before it's online?
It wouldn't be accepted, because 2-3-stable is frozen except for security bugs.
Now I do understand the relation between projects =)
Though - while I see it’s quite natural to freeze the code, I still have lots of projects on Rails 2.3 and use the guides. It’s a great collection of resources opposed to blog posts spread across the interwebs.
And I think the guides could really benefit from independent deployments.