On Aug 29, 2006, at 6:22 PM, James Britt wrote:
Mat Schaffer wrote:
I made some major changes to the document today to start moving
it toward the guide I see it as. Just wanted to call attention
to it so that people could offer comment. I'd like to flesh out
the stdlib- doc instructions more still and maybe reword some of
the guidelines. But that will take some time. I also need to
test the command I provided for checking out the 1_8 branch. I
just got it from a CVS tutorial.
I haven't published it yet, so I don't think anyone not
associated with the writely document can view it.
Question: The guide first show how to fetch the Ruby source using
"co ruby", but then says to get the 1.8 branch, using "co ruby_1_8
ruby"
I'm going off of what Eric said to work off HEAD and he'll back-port
if the 1.8 change is trivial here. Am I mistaken?
I also think that anyone doc'ing the code needs to have it compiled
and running so that they can see that the code really does what the
docs as are describing.
Cool. I haven't tried to compile ruby yet fearing that it might be
complicated and no-one's recommended it yet. Do you know the build
process?
(The installed Ruby need not be on the same box one uses for
editing the docs and creating the cvs diffs, but people claiming to
know what the docs should or shouldn't be have to have first-hand
experience with a running system someplace.)
This seems like a border case to me, but maybe my single-computer
view is skewed. If there's something you think it should say about
that, go for it!
This may seem like a big "Duh", but I'm wondering if this guide
should be explicitly focused on improving docs for the current
stable release. Instructions and such should be worded so that
people do not accidentally end up with Ruby 1.9.
As above, I understood we were supposed to work on the HEAD. Not
sure if that qualifies as 1.9 or not from a terminology standpoint.
I expect (I'm guessing, really) that most people interested in
contributing doc patches are going to be folks running the current
stable release and who find that existing docs do not match their
experience with the actual code. Something in the guide should
explain that these are instructions for improving the *current*
stable release, and that one must verify that the installation they
are using as a reality check is the same code (and not, say, 1.8.4).
Good point. I'm think there should be stuff included in the setup
docs to talk about testing the behavior of both branches before
submission.
And all examples should ensure that cvs operations work against
the current stable release.
I was planning on verifying it, but my afternoon was pretty busy.
I'll get to it at some point unless people beat me to it.
Of course, I'm sure a lot of people (most of you) on this list that
know more about the process than I do. I just got here so I'm
writing from what I've discovered so far. If there's something you
think the document should have that isn't there, add it in, even just
as a rough outline of a section. Hopefully it will outline the
process of discovery as I'm going through it so more people can help
without this trial and error process.
-Mat
|
