How do I tell what version a guide is for?

hi,

I was looking at Ruby on Rails Guides: Active Record Query Interface 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 Ruby on Rails Guides: Active Record Query Interface 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

    Contributing to Ruby on Rails — Ruby on Rails Guides

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:

Ruby on Rails Guides: Active Record Query Interface 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