CDR Tickets

I have finished a draft of the documentation for the build and deploy scripts. It's on the Production CDR server, in document CDR0000779289.

I have not tried to place it in the hierarchy of broader or related terms, and have not added any metadata. However the text is ready for initial review.

Following a suggestion from Bob, I have added Aarti and Blair to this issue. If possible, I'd like one or both to review the draft documentation of the CDR build and deploy process and note any questions, comments, criticisms, or suggestions on the document.

The document ID is CDR0000779289 on the Production CDR Server. I've printed out copies of the document so that it won't be necessary to use XMetal or to view raw XML in a web browser. I've put one copy each on Aarti's and Blair's desks. The document is revised from the first version.

I'll be in again on Tuesday to make any needed corrections.

Reading through this, it's a wonderful high-level explanation of what the build and deploy scripts do, and the reasons why they do these steps. That sort of information is frequently left to collective memory, so it's good to have it written down for easy reference.

What's missing however is the day-to-day "How do I use this?" Some of the questions I'm left with are:

• Where do I find the build script? (Both on the dev server and in SVN)

• How do I invoke it?

• What steps do I need to perform in order to do a build? (Pre-run and post-run)

• Where do the files end up?

I can find some of this by digging through the document, but for someone who doesn't already know the CDR system, it would be helpful to have "recipes" for "Here's how to perform a build". "Here's how to perform a deployment." (The XMetal installation instructions are a good example.)

I agree with Blair. In addition to that, as I was reading through the document I had the following questions:

• Run build phase on CDR Dev server - which particular server?

• Network drive accessible from the target server - which network drive? Is there a specific drive set up for this purpose?

• Build Phase - what is the difference between build-all.py and build.py?

• build-python-dir.cmd - what are the possible arguments?

Thank you.

Thanks for the helpful reviews.

I'll be in the office tomorrow and will modify the document to answer the questions.

I agree with both, Blair and Aarti regarding the need for more detail. As a new programmer or - like me - one who has never run the build process before I would like samples of the commands to submit written down in addition to other little details:

• Do I run this in a specific directory or anywhere?

• When I start the build script how long does it (typically) run?

• What's the console output to be expected?

• Where does the command build-all.py live?

  d:\cdr\Build\AnthillPro\build-all.py

• Do I pass any command line options, username/password, etc?
  The --help option lists every option available but there may be more than one option required. It seems to me the command must be submitted at a minimum as:

  $ build-all.py --svnuser <mymyself> --svnpass <mysecretpw> --svnbrnch Darwin

  Why didn't we use the option

  --svnbranch

  instead of

  --svnbrnch

  Why is the default for the --srcpath option d:\cdr\Filters\output? That directory is usually used for filter output from test publishing jobs.

I have more but JIRA will fail saving this comment if I don't submit the comment soon. :-)

By the way, I've added the Style attribute for the ordered lists which aren't set by default in XMetaL.

We would also like to add a date to the document so one will know when it had last been updated.

I'll answer the hard questions here:

--svnbrnch vs --svnbranch
I wanted the columns to line up nicely. "--svnbranch" was one character longer than any of the other commands, which would require me to move everything over a character.

There are some other abbreviations, so maybe that one isn't out of line
--srcpath instead of --source-path
--execcmd instead of --execute-command
--helpcmds instead of --help-commands

Required parameters:
I'll beef up the usage message, but --svnbrnch is the only required parm if your svnuser and password are cached. I probably should have made the svn branch an ordinary parameter instead of a – option since it's not optional. I can do that if desired. Maybe I will. There still just enough time for me to introduce a new bug.

I've stored a new version of the document. There are small changes throughout to fix grammar or make some points clearer. The most significant change is the addition of a new topic section called "Example Build / Deploy Scenario". I'm hoping that it gives the answers to the practical questions raised in earlier comments on this issue. The specific recommendations for disk, directory, and file locations are gathered together in the "Notes" section below that and referenced from above.

One question I didn't answer in the document is Aarti's question about the parameters to build-pythondir.cmd. Ideally, a programmer will never need to pass any arguments at all since it's invoked by the higher level build-all.py, which knows what to pass and/or what to put in the environment, rather than run by the programmer directly on the command line - though running build-pythondir.cmd directly will give a list of expected parameters. In the usual case, a change to one of the parameters, such as the svn userid or password, will be accomplished by passing parameters to build-all.py, which passes the change to all subsidiary scripts, rather than passing the info directly to build-pythondir.cmd on the command line.

Ever an optimist, I have removed "[DRAFT]" from the title of the document. However I have not attempted to integrate the document into the Documentation table of contents. I'll leave that to Volker to do, and to add any cross references or metadata that he deems appropriate.

https://collaborate.nci.nih.gov/display/OCECTBWIKI/CDR+Release+Deployment+How-To

Done and reviewed/tested by Volker.

If you're satisfied that this is done, ~volker, please close this ticket.

Thanks,
Bob

I'm certain this is a living document that will have updates with almost every new release and hibernating in between but for the purpose of this ticket we should be able to close it. With this document I feel confident in case I'll have to perform the release myself even without the expert guidance of Bob.