Over the years I have seen some confusion about what is exactly
and how it relates to the documentation of Ruby on Rails.
This post explains everything you want to know about this aspect of the project.
What is docrails?
docrails is a branch of Ruby on Rails with
public write access where anyone can push doc fixes.
If you see a typo, you’d like to correct a factual error, complement some
existing documentation, add a useful example… before docrails existed you had
to open a pull request (or the equivalent in those days) and follow the ordinary
workflow to get it accepted. docrails allows you to clone the repo, edit, and
ZOMG, that’s awesome! Tell me more!
Changes to the code base need review before they are pushed. Each individual new
feature or bug fix needs the perspective and responsability of core team
members to take a decision about it.
Documentation fixes, though, are much more likely to be fine as they are. So,
docrails has a public write policy to ease the workflow for contributors.
All commits have to be reviewed anyway, so docrails needs the same effort from
Rails committers than going through pull requests, please everyone give big
props to Vijay Dev who is nowadays in charge
of this time consuming task.
The point of docrails is to provide a way to contribute to the Rails documentation
that is fast and easy for contributors.
But wait, I am editing some separate thing?
docrails is a separate branch because it has a different access policy, but
you are editing the actual Ruby on Rails documentation.
Every few days, once all new commits are reviewed docrails is merged into
master, and master is merged into docrails. Also, very important edits may be
cherry-picked into stable branches at the discrection of who merges.
What is allowed in docrails?
You can freely push changes to any RDoc, guides, and READMEs.
No code can be touched at all. That’s a hard rule. No matter how insignificant,
not even a one character typo in a string literal.
CHANGELOGs cannot be edited either.
Is docrails a documentation project?
No, Ruby on Rails has no documentation project. Treating documentation as a
separate aspect of the project would be similar to treating testing as an
external part of the project.
Documentation is an integral part of the development of Ruby on Rails.
Contributing a feature or bug fix means contributing its code, test coverage,
I am preparing a pull request, should I document later via docrails?
No, docrails is meant only for quick doc fixes.
Pull requests should be complete: code, tests, and docs. If a pull request lacks
any of those in general it won’t be accepted as is.
Also, updating docs does not only mean that you edit the RDoc next to the code
you are touching. Often the change needs grepping the project tree to find
instances of what the pull request is about, to update examples, revise
explanations affected by your change, or writing new documentation.
Tidbit: run ack -a to have guides included in the search.
I made a doc fix, when is it going to be online?
Rails releases are a complete set. The documentation itself is part of the
release. The fix is going to be online in the stable API or
guides websites when
the branch that contains the fix gets released.
Edits merged into master are always online in the edge API
and edge guides,
which are regenerated after every push to master. Thus, edits done via docrails
are online in the edge docs website after the next docrails/master cross-merge.
Can I open pull requests for documentation fixes in Ruby on Rails?
Absolutely. Specially if you are unsure about the fix. But if you feel confident
just push to docrails.
Please do not open pull requests in docrails.
Note that docrails has no issues tab. The reason is docrails is not a project,
as explained above, only a way to bypass pull requests. Documentation issues are
Ruby on Rails issues and belong to the Ruby on Rails project just as any other
kind of issue.
Does Ruby on Rails has documenters?
No, documentation comes with each push to master. Everyone documents Rails.
The only exception is guide authors. Guide authors take the task to write an
entire new guide about a certain topic, and they are allowed to push early
drafts to docrails for convenience (only guides in the public index are
considered to be published).
That’s for new guides. Once published, guides maintenance happens in master as