How do I tell what version a guide is for?

hi,

I was looking at http://guides.rubyonrails.org/v2.3.8/active_record_querying.html
and noted that there is nothing on named_scopes even though they are
mentioned in the list in the top of the page.

I then looked for how to contribute as I thought I'd add something
about it, but browsing:

https://github.com/lifo/docrails/tree/master/railties/guides/source

I can only find the 3.0 version of the file.

Can you guys point me to the right file?

Another thing. Are the guides for different versions of Rails,
organized in some way? I don't see the pattern..

Best regards

Henrik Loevborg

I was looking at http://guides.rubyonrails.org/v2.3.8/active_record_querying.html
and noted that there is nothing on named_scopes even though they are
mentioned in the list in the top of the page.

That's a bug in the guide of that release.

I then looked for how to contribute as I thought I'd add something
about it, but browsing:

https://github.com/lifo/docrails/tree/master/railties/guides/source

I can only find the 3.0 version of the file.

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.

Please see also

    http://guides.rubyonrails.org/contributing_to_ruby_on_rails.html

Can you guys point me to the right file?

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.

thank you for your answer.

My request is specifically on the rails guides. I’d like to add to this guide:

http://guides.rubyonrails.org/v2.3.8/active_record_querying.html

as there is nothing on named scopes.

It is my understanding that I can find the textile source in the docrails project (https://github.com/lifo/docrails) under

railties - guides - source

however, I can’t seem to find the rails 2.3 version of it. If I understand your answer correctly, I have to do it in the source of the Rails project?

Best regards

  • Henrik

My request is specifically on the rails guides. I'd like to add to this
guide:

http://guides.rubyonrails.org/v2.3.8/active_record_querying.html
as there is nothing on named scopes.

That'd be good, but the 2-3-stable branch is basically frozen, it only
gets security fixes nowadays basically.

It is my understanding that I can find the textile source in the docrails
project (https://github.com/lifo/docrails) under
railties - guides - source

That's right. If you do a regular clone of the repository, those are
what we call the "edge" guides. These guides are the ones published in

    http://edgeguides.rubyonrails.org/

And as time passes that will evolve into what Rails 3.2 will be.

however, I can't seem to find the rails 2.3 version of it. If I understand
your answer correctly, I have to do it in the source of the Rails project?

In order to see the guides of the 2-3-stable branch within a checkout
of the repo you need to switch to that branch:

    git checkout 2-3-stable

Rails versions are tagged. To get the exact state of the project tree
for version 2.3.8:

    git checkout v2.3.8

Though such a tree state is completely frozen, because that's a
release. Once can only patch ongoing branches.

Oh - I thought the guides were an independent project..

But that's just the edge ones? Sorry, I'm a bit confused :slight_smile:

- Henrik

Ah! I see, no prob, let me explain.

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.)

Do you see how this works better now?

Except for patches specific to a branch, rather than backported. Once
you see how's organized, you see how it works anyway.

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.

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?

Thanks for taking time to explain how it works

- Henrik

Hey Henrik,

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.

Thanks
Vijay

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.

Just my thoughts as I’ve come to understand it =)

  • Henrik