getting going with the reviewing

[Tim Menzies]

dear all,

i write to suggest that, in order to facilitate reviewing, the
programmers (panos, michaelS, mahesh, me) should CLOSE the content on
their current files and only add new content to other OPEN files. in
this approach, MichaelR and Lorance have something stable to review.
i.e.

CLOSED files:
zMahesh.awk
zMich.awk
zPanos.awk
zTimm.awk

OPEN files:
zMahesh1.awk
zMich1.awk
zPanos1.awk
zTimm1.awk

dear michaelR and Lorance,

do f you wanted me to work up a short checklist (say, a dozen items)
of things to check when reviewing cookbook entries? alternatively, do
you have your own checklist already in mind?

enjoy!
:-)

t

[Lorance Stinson]

I have been away this weekend and do not know my availability on
weekends for the next several months. I will try to come up to speed
on the state of the project this week. If you want to hand me a few
tasks I will see what I can work through.

> To unsubscribe from this group, send email to awkcookbook+unsubscribegooglegroups.com or reply to this email with the words "REMOVE ME" as the subject.
>

--
http://lorance.freeshell.org/
(678) 683-9149

[Michael Richter]

On 29 March 2010 23:40, Tim Menzies <menzi...@gmail.com> wrote:

dear michaelR and Lorance,

do f you wanted me to work up a short checklist (say, a dozen items)
of things to check when reviewing cookbook entries? alternatively, do
you have your own checklist already in mind?

enjoy!
:-)

I can see room for both.  Having a standard reviewer checklist is good to assure a quality baseline.  Adding my own will help catch the things you didn't/couldn't/didn't-want-to conceive. 

If you can assign a few tasks to me (and tell me how to receive notifications) I'll start my reviewing ASAP.

--
"Perhaps people don't believe this, but throughout all of the discussions of entering China our focus has really been what's best for the Chinese people. It's not been about our revenue or profit or whatnot."
--Sergey Brin, demonstrating the emptiness of the "don't be evil" mantra.

[Panos]

Dear fellows,
I'm too busy this period, so I'll take a rest for about a month.
In order not to slow down your work, I'll rejoin, if necessary,
with zPanos1.awk, which I've already created (empty) in order
to remember that I'll have to work in that file in the future.

Congratulations for the great job you are doing all of you.
I'll follow the mailing list of course and keep in touch.
Thanks.

[Tim Menzies]

dear all,

i'm after comments on how to handle our reviewing process. to that
end, please take a look at http://awkcookbook.info/?reviewing.
comments? suggestions?

dear lorance and michael,

since we are debugging our procedures, i'd like to suggest a look
before we leap.

lorance: can you take zTimm.awk?
michael: can you take zPanos.awk?

to find the above files, see http://code.google.com/p/awk/source/browse/#svn/trunk/content.

IMPORTANT : please do not review zTimm1.awk and zPanos1.awk- these
contain new stuff not ready for review

those files contain many web page. can you review, say, 10 pages each
and see how long it takes?

then lets pause and reflect on what we can do to make the reviewing
easier (e.g. if it is taking too long, we need to do something about
that).

i want to use googlecode for the reviewing (it has some nice issue
tracking stuff) for instructions on that reviewing process, see
http://awkcookbook.info/?reviewing

thanks!

t

[Tim Menzies]

On Wed, Mar 31, 2010 at 10:28 AM, Lorance Stinson
<lorance...@gmail.com> wrote:
> This is starting to seem like a confusing process. Is this based on an
> existing method or something new?

the googlecode stuff is pretty standard open source code sharing tools.

but heh, one way to simplify everything is that you just read stuff
and email me comments and i handle the code changes and integration
and test suite updates and all the communication with the developers.

simple!

but i dream of being able to decentralize my task. the cookbook is a
shared coding resource designed for a large group to work at the code.
yes, there will be a learning curve coming into that group but the
learning curve is mostly about a set of tools 100% absent from the
standard awk-verse (that enable sharing etc).

so if my stuff is too complex, screw it. just read stuff and email be
comments. no worries.

> I can see updates quickly get out of
> hand as changes have to be ported between multiple revisions of files,
> rather defeating the point of the version control system.

the VC issue is simple.

1) the coders write files

2) at end of month the coders freeze their code and start working on new files

3) reviewers work on last months files.

4) when the reviewers are done, i empty the reviewed files, moving
their content to some "done" set.

> I will do my best to keep up with the process though...

or propose something simpler! either way works.

enjoy!
:-)

t

>> --
>> To unsubscribe, reply using "remove me" as the subject.

>>
>
>
>
> --
> http://lorance.freeshell.org/
> (678) 683-9149
>

--
there are those who call me... tim (menzies, ph.d.)
morgantown (39.6n, -79w), usa
assoc prof csee, wvu
http://menzies.us
1-304-376-2859

PROBLEM: Handling e-mail is very very very slow, resulting in inbox overflow.
SOLUTION: Adopt the "http://four.sentenc.es" policy: no responses
longer than 4 sentences. It’s that simple. Care to try it?

[Lorance Stinson]

I didn't mean the use of Google Code, that makes sense and is a good
idea. I meant the way of using Subversion. Keeping multiple files, and
packing so much into single files, could get unwieldy. If it works for
everyone then great. I do rather like the idea of using the issue
tracker for reviews though...

[Tim Menzies]

ah! i understand. you are suggesting that we use one page per file? which would give us an atomic unit of review?

er.. do you want to go even further? we could have subdirectories for the different stages of review. e.g. 

1) new stuff goes into content/new 

2) when its reviewed it moves into content/reviewed then to content/revised

3) then reviewers get to it again and either drop it back to content/reviewed (if it needs more work) or content/done (if they are done).

the advantage of the above is that you don't have to think about what is to be reviewed- basically, anything in content/new or content/revised.

disadvantages?

t

[Lorance Stinson]

Depending on how much the project grows one page per file might work
well. And having the chapters in subdirectories would make it a bit
cleaner. Branching might also be useful, as could tagging. Subversion
makes this very easy and it doesn't consume any space unless changes
are made.

I like the issue tracker but think that could be used more
proactively. Say I wrote a new section, or updated one. I could then
open an issue on that revision. Someone else could claim the issue and
do the review. Once the review is completed I or someone else could
apply the necessary changes. Rather, rinse, repeat till clean, err,
published.

You might also think very soon about using a different markup system.
I know O'Reilly has used DocBook for their books in the past. Perl POD
might also be a workable solution since it is so easily transformed
into alternate formats. I don't have experience with Tex but I imagine
that would also be a very workable solution. And since all of those
are so easily transformed into web pages, PDF files and other formats
they would make processing much easier later on. Though Markdown might
have all of those too, I have not used it much.

[Tim Menzies]

hey Lorance,

still not quite following your idea. lets see if i have it

since we have chapters for numbers, strings, datetime, etc then in
your proposal we would have sub-directories for strings, datetime,
etc. where would reviewers look for stuff to review next? would this
sub-dirs have sub-sub dirs for new, revised, etc?

plan b would be to NOT use directories but instead use the tags given
to every file. sure, make each page a seperate file but add special
tags to the start-of-file. for example, right now, when i creagte a
file, i give it a name, some tags, and a heading:

fname
Strings Timm Apr10

Heading for this file

we could adopt some convention on the tagging, e.g. New NeedsReview
etc and the the query

http://awkcookbook.info/?NeedsReview

would reveal all the ones needing a review.

comments?

t

p.s. regarding your suggestion to use PerlPod and Markdown, note that
the current scheme in the cookbook uses the PerlPod convention of
"code is indented by one blank" and non-code is written in a
Markdown-like syntax

On Wed, Mar 31, 2010 at 2:56 PM, Lorance Stinson

[Lorance Stinson]

On Thu, Apr 1, 2010 at 4:14 AM, Tim Menzies <t...@menzies.us> wrote:
> hey Lorance,
>
> still not quite following your idea. lets see if i have it

I'm mostly thinking out loud. I think I've meddled enough by now
though. Time for me to get to work reviewing. I'll try to get to that
tomorrow, busy with work and all...

> since we  have chapters for numbers, strings, datetime, etc then  in
> your proposal we would have sub-directories for strings, datetime,
> etc. where would reviewers look for stuff to review next? would this
> sub-dirs have sub-sub dirs for new, revised, etc?
>
> plan b would be to NOT use directories but instead use the tags given
> to every file. sure, make each page a seperate file but add special
> tags to the start-of-file. for example, right now, when i creagte a
> file, i give it a name, some tags, and a heading:

Subdirectories for the structure and tags for the state (ready for
review, to be updated, updated...) is about what I'm thinking. Just a
thought though.

>  fname
>  Strings Timm Apr10
>
>  Heading for this file
>
> we could adopt some convention on the tagging, e.g. New NeedsReview
> etc and the the query
>
>  http://awkcookbook.info/?NeedsReview
>
> would reveal all the ones needing a review.
>
> comments?

Yeah, something like that. Tags can be very useful. But really how you
all want to do it is fine with me. I just don't want to see this
project fail. I've wished I had this book many times in the past.

> t
>
> p.s. regarding your suggestion to use PerlPod and Markdown, note that
> the current scheme in the cookbook uses the PerlPod convention of
> "code is indented by one blank" and non-code is written in a
> Markdown-like syntax

I noticed that. Pretty good idea.

[Tim Menzies]

On Thu, Apr 1, 2010 at 6:19 AM, Lorance Stinson
<lorance...@gmail.com> wrote:
> On Thu, Apr 1, 2010 at 4:14 AM, Tim Menzies <t...@menzies.us> wrote:
>> plan b would be to NOT use directories but instead use the tags
>

> Subdirectories for the structure and tags for the state (ready for
> review, to be updated, updated...) is about what I'm thinking.

ok- so the idea is....

1) one page per file. and that's going to be a lot of files so...

2) adding directories for the structure (strings, numbers, dateTime,
etc) sounds like a v.good idea.

3) tags for the state.

regarding states, I'm thinking four (see
http://awk.googlecode.com/svn/trunk/share/img/reviewingStates.png):

- Sandbox (place where we can play without bothering the reviewers)
- Revised (wake up the reviewers)
- Reviewed (wake up the programmers again)
- Ready (everyone happy.)

in this model, if a reviewer sees a Revised page they review it and
make it either Reviewed (if they want changes) or Ready (if they pass
it, as is). If a programmer see their pages are Reviewed, then they
make changes and make it Revised.

but before i implement the above, i want a "ping" from mike, panos,
and mahesh (our coders). any comment on this rearrangement?

t

[Michael Richter]

OK, I am now completely bewildered by the process here.  (For starters I'm not an SVN user so have zero familiarity with the tools.)

The instructions on what to review are clear to me, but the rest is utterly baffling to the point I can't even begin to do any kind of meaningful review.

[Tim Menzies]

On Fri, Apr 2, 2010 at 11:00 AM, Michael Richter <ttmri...@gmail.com> wrote:
> OK, I am now completely bewildered by the process here.  (For starters I'm
> not an SVN user so have zero familiarity with the tools.)

yes- it is hard to review something when that something is undergoing
mass change.

lets try this:

1) wait a few days while i terminate on the code re-org. i'll ping you
when the file structures are stable again (early next week)

2) in the meantime, see if you can do the reviewing without any svn.
go to http://code.google.com/p/awk/source/browse/trunk/content/examplePage.txt,
find something you want to see changed (e.g. a typo) and double click
on that line. that should pop up a comment box and you can type stuff.
enter one comment and see if you can save it. ping me when you've
done that and i'll see if your comments are in.

t

[Michael Richter]

OK, I've put a few comments in the test  document.  The feedback system online is actually surprisingly decent if it works to the point that you can see them.

[Tim Menzies]

huh, can't see them.

did a "publish" comments button appear right hand side? did you push
them as well?

t

[Michael Richter]

Uh... I didn't see one, no, but wasn't looking either.  Let me try again.

[Michael Richter]

OK, try now.  "Button" is a strong word there.  It was an indistinguishable link in a mass of text.

[Tim Menzies]

michael,
i got it- your comments directly emailed to me. very cool. so, once i
finish the source code re-org, we can start in earnest.

leonard,
need to modify our previous plan. michaelR is a non-svn user but can
still use the click and point comment tools of googlecode to review
stuff. so to use the "tag" idea to store what files are
sandbox/revised/reviewed/ready, we'll have to make those tags
googlecode tags, not tags in the actual source code. (that is do-able,
BTW, googlecode lets us define our own custom tags). anyway, i'll do
the source code re-org this weekend and then we can start in earnest.

who is the earnest guy anyway?

t

[Michael Richter]

I'm wondering if there's a reason you chose SVN over some of the other options like Mercurial, Darcs, Fossil, etc.?

[Tim Menzies]

google code supports svn or mecurial so the choice is limited to those
two

and linux journal reports that svn is the most popular (see
http://www.linuxjournal.com/magazine/readers-choice-awards-2009?page=0,2)

on the other hand, you got experience with these other version control
systems? and you'd recommend them?

t

On Apr 3, 10:17 pm, Michael Richter <ttmrich...@gmail.com> wrote:
> I'm wondering if there's a reason you chose SVN over some of the other
> options like Mercurial, Darcs, Fossil, etc.?
>
> On 4 April 2010 04:19, Tim Menzies <t...@menzies.us> wrote:
>
>
>
> > michael,
> > i got it- your comments directly emailed to me. very cool. so, once i
> > finish the source code re-org, we can start in earnest.
>
> > leonard,
> > need to modify our previous plan. michaelR is a non-svn user but can
> > still use the click and point comment tools of googlecode to review
> > stuff. so to use the "tag" idea to store what files are
> > sandbox/revised/reviewed/ready, we'll have to make those tags
> > googlecode tags, not tags in the actual source code. (that is do-able,
> > BTW, googlecode lets us define our own custom tags). anyway, i'll do
> > the source code re-org this weekend and then we can start in earnest.
>
> > who is the earnest guy anyway?
>
> > t
>

> > On Sat, Apr 3, 2010 at 9:18 AM, Michael Richter <ttmrich...@gmail.com>

> > wrote:
> > > OK, try now.  "Button" is a strong word there.  It was an
> > indistinguishable
> > > link in a mass of text.
>

> > > On 3 April 2010 21:16, Michael Richter <ttmrich...@gmail.com> wrote:
>
> > >> Uh... I didn't see one, no, but wasn't looking either.  Let me try
> > again.
>
> > >> On 3 April 2010 11:53, Tim Menzies <t...@menzies.us> wrote:
>
> > >>> huh, can't see them.
>
> > >>> did a "publish" comments button appear right hand side? did you push
> > >>> them as well?
>
> > >>> t
>

> > >>> On Fri, Apr 2, 2010 at 11:38 PM, Michael Richter <ttmrich...@gmail.com

>
> > >>> wrote:
> > >>> > OK, I've put a few comments in the test  document.  The feedback
> > system
> > >>> > online is actually surprisingly decent if it works to the point that
> > >>> > you can
> > >>> > see them.
>
> > >>> > On 3 April 2010 00:15, Tim Menzies <t...@menzies.us> wrote:
>
> > >>> >> On Fri, Apr 2, 2010 at 11:00 AM, Michael Richter

> > >>> >> <ttmrich...@gmail.com>

> > >>> >> >> >>>> <lorancestin...@gmail.com>

> > >>> >> >> >>>> wrote:
>
> > >>> >> >> >>>>> I didn't mean the use of Google Code, that makes sense and
> > is
> > >>> >> >> >>>>> a
> > >>> >> >> >>>>> good
> > >>> >> >> >>>>> idea. I meant the way of using Subversion. Keeping multiple
> > >>> >> >> >>>>> files,
> > >>> >> >> >>>>> and
> > >>> >> >> >>>>> packing so much into single files, could get unwieldy. If
> > it
> > >>> >> >> >>>>> works
> > >>> >> >> >>>>> for
> > >>> >> >> >>>>> everyone then great. I do rather like the idea of using the
> > >>> >> >> >>>>> issue
> > >>> >> >> >>>>> tracker for reviews though...
>

> > >>> >> >> >>>>> On Wed, Mar 31, 2010 at 1:44 PM, Tim Menzies...
>
> read more »

[Michael Richter]

I've used Mercurial and Darcs and use Fossil for my private projects now.  I prefer all three to SVN (to the point that I actually use them and recoiled from using SVN).

--

To unsubscribe, reply using "remove me" as the subject.

--