diff options
Diffstat (limited to 'ACE/docs/bczar')
| -rw-r--r-- | ACE/docs/bczar/bczar.html | 372 | ||||
| -rw-r--r-- | ACE/docs/bczar/privileges.html | 63 |
2 files changed, 435 insertions, 0 deletions
diff --git a/ACE/docs/bczar/bczar.html b/ACE/docs/bczar/bczar.html new file mode 100644 index 00000000000..7e076de8c83 --- /dev/null +++ b/ACE/docs/bczar/bczar.html @@ -0,0 +1,372 @@ +<!-- $Id$ --> + +<html> +<head> +<title>The realm of the build czar</title> +</head> + +<h2>Build Czar Duties</h2> +<p> + + Th main duties of the Build Czar are summarized as follows + + <li> Continuously monitor the builds using the <a + href="http://www.dre.vanderbilt.edu/scoreboard"> Scoreboard </a> as + one of the primary source of information. + + <li> Notify developers who broke compilation to fix the errors as + soon as possible, ideally by the next day. A red color in the + "Compile" column is not at all acceptable - the Build Czar needs to + ensure that these problems are identified and fixed in a timely + manner. If possible, the Build Czar should let developers know what + the source of problems might be. It is quite possible that + developers who checked in the code or users who provided the patch + may not have resources to investigate the issues, so the Builds + Czar's help is essential to keep things moving ahead. + + <li> Keep an eye on the tests that are run in every build. Anything + abnormal needs to be notified to the right developer. The Build Czar + should try helping the developer by providing stack traces (in case + of crashes) or other details like printouts with debugging level + turned on. + + <li> Some tests fail in the daily builds for many reasons like known + bugs, transient timeouts etc. Make sure that no new test failures + show up. This <a href="mailto:jwillemsen@remedy.nl">guy</a> knows + most of the information. Ask him to help you out with known + problems. + + <li> Keep an eye on the <a + href="http://www.dre.vanderbilt.edu/Stats">footprint and + performance</a> stats. Any abnormal changes should be brought to + the attention of the developer resposible for it or to the <a + href="mailto:devo-group@list.isis.vanderbilt.edu">devo group</a>. + + <li> Keep the builds ticking. Any red on the "Last Finished" column + in the Scoreboard should be fixed. The link to the "Build Name" + indicates the machine where the build is being run. + + <li> The builds don't cover all the possible configurations. If you + get a bug report about a compile error in a particular + configuration, try setting up a build to make sure that it doesn't + show up again if it has been fixed. + + <li> Keep an eye on the <a + href="http://deuce.doc.wustl.edu/bugzilla/index.cgi">bugzilla </a> + entries that are registered by users and developers. Decide on the + bugs that need to be fixed for the beta and pain developers for an + ETA. + +</p> + +<P> The document <a href="./privileges.html"> here </a> talks about +the powers of a build Czar. </P> + +<P> The Build Czar is empowered to set up more builds on his own for +his convenience. This +<a + href="https://svn.dre.vanderbilt.edu/viewvc/ACE_autobuild/trunk/README?revision=HEAD"> +page </a> has a +step by step instructions on how to do that. </P> + +<P> The build czar can get the build configuration by looking at the +config portion of the scoreboard. </P> + +<p>Pro-active involvement by the build czar is necessary. Being +a pro-active build czar requires monitoring the subversion +archive carefully and responding quickly to suspected changes to keep + the repo stays stable.</p> + +<hr> +<h2>Recipe for Cutting a Beta/Minor Kit</h2> + +<P> The build czar is also in charge for the release of the +beta. Cutting a beta is as simple as cutting butter if things go +well. Here is the procedure followed while cutting a beta: + +<ol> +<li>The whole process takes somewhere between 8-9 hours, about 2 hours +for making the release itself and the remaining time for generating +the doxygen documentation.</li> +<li>I suggest you take advantage of GNU Screen so that even if your SSH session +is interrupted, the cutting process can continue. +<ul> +<li> type <code>screen</code> to start screen.</li> +<li> execute commands as normal. Note that Ctrl-A is special in screen, so you +need to type Ctrl-A-A to send a Ctrl-A to the shell</li> +<li> should your session be interrupted, reconnect and type <code>screen -x</code></li> +<li> when finished, just type exit twice</li> +</ul> +<li>Prior to starting this, gather aggregate release notes from all +developers. This is usually in the form of an email plea asking for +a writeup of significant changes since the last beta. Add these notes +to the NEWS files before cutting the release so that all notes are +part of the release.</li> +<li>Checkout a new workspace on <tt>anduril.dre.vanderbilt.edu</tt></li> +<ul> +<li> +The best place to create the workspace is under /export/anduriltmp/bczar. Don't use +the home directory itself, it is an NFS share and not really fast. +</li> +<li>Checkout like this: +<ul><li>svn co --username <your user id> https://svn.dre.vanderbilt.edu/DOC/Middleware/trunk DOC_ROOT</li> + <li>svn co --username <your user id> https://svn.dre.vanderbilt.edu/DOC/MPC/trunk DOC_ROOT/ACE/MPC</li> +</ul> +</ul> +<li> Set $DOC_ROOT to point to the new +workspace you checked out.</li> +<li> Set an environment variable SIGNATURE indicating your full +name. This is used to fill the ChangeLog entry.</li> +<ul><li>For example,<tt>export SIGNATURE="Chris Cleeland"</tt></li></ul> +<li> Set an environment variable MAILID indicating your mail id. This +is used to fill the mail id portion of the ChangeLog entry.</li> +<ul><li>For example,<tt>export MAILID="cleeland@ociweb.com"</tt></li></ul> +<li> Change directories to to <tt>$DOC_ROOT</tt> </li> +<li> Tag the release by executing <code>ACE/bin/make_release.py --beta --update --tag</code> This will only +take a couple minutes to complete.</li> +<li> Create the kits by executing <code>ACE/bin/make_release.py --kit </code> This will take about two hours to complete. + +<ul><li>These commands only tags and creates the kits for the + software itself, not documentation. </li> +<li>The kits end up in <tt>/export/anduriltmp/bczar/packages</tt></li> +</ul> +<p> +To summarize, the following is a transcript of the steps up to this point executing +successfully: <p> +<code> +sm@beatrice ~<br> +$ ssh bczar@anduril.dre.vanderbilt.edu<br> +No default printer<br> +-bash-3.00$ cd /export/anduriltmp/bczar<br> +-bash-3.00$ export DOC_ROOT=$PWD/DOC_ROOT<br> +-bash-3.00$ export SIGNATURE="Simon McQueen"<br> +-bash-3.00$ export MAILID=sm@prismtech.com<br> +-bash-3.00$ svn co https://svn.dre.vanderbilt.edu/DOC/Middleware/trunk DOC_ROOT<br> +-bash-3.00$ svn co https://svn.dre.vanderbilt.edu/DOC/MPC/trunk DOC_ROOT/ACE/MPC<br> +-bash-3.00$ cd DOC_ROOT/<br> +-bash-3.00$ ACE/bin/make_release.py --beta --update --tag<br> +-bash-3.00$ ACE/bin/make_release.py --kit<br> +</code> +<p> +Feel free to cut and paste with suitable edits. +<li>In the <em>EXTREMELY</em> unlikely event that something goes wrong during the +<em>tagging</em> of the repo (ie, make_release -v beta -u), +the following files must be returned to the state they were in before the release +process started and then checked back into SVN:<br><code> +ACE/ChangeLog<br> +ACE/PROBLEM-REPORT-FORM<br> +ACE/VERSION<br> +ACE/TAO/ChangeLog<br> +ACE/TAO/PROBLEM-REPORT-FORM<br> +TAO/VERSION<br> +CIAO/ChangeLog<br> +CIAO/PROBLEM-REPORT-FORM<br> +CIAO/VERSION<br> +CIAO/ciao/Version.h<br> +TAO/tao/Version.h<br> +ace/Version.h<br></code><p> +In most cases, a <code>svn revert -R *</code> from DOC_ROOT will suffice.<br /> +The tag will also need to be removed (both in Middleware and MPC): ACE+TAO+CIAO-X_Y_Z +(where X and Y are the minor and beta release numbers of the release that is to be restarted).<p> +E.g.:<br> +<code> +svn rm https://svn.dre.vanderbilt.edu/DOC/Middleware/tags/ACE+TAO+CIAO-X_Y_Z<br /> +svn rm https://svn.dre.vanderbilt.edu/DOC/MPC/tags/ACE+TAO+CIAO-X_Y_Z<br /> +</code> + +Note that this <em>only</em> needs to be done if the <em>tagging</em> fails. If kit creation +fails, simply restart that process. +<li>The packages end up by default under $DOC_ROOT/packages-PID, you can copy them to the webserver using the following commands. At the moment +you execute these commands all users can download these packages.</li> +<code> +cp $DOC_ROOT/packages-PID/ACE* /export/www/download.dre/ACE+TAO-distribution<br> +</code> +<li>After the repository is tagged you can start generating the doxygen +documentation.</li> +<li>Login to naboo.dre.vanderbilt.edu as bczar: <code>ssh bczar@naboo.dre.vanderbilt.edu</code></li> +<ul><li>After login, ssh to bczar@download.dre.vanderbilt.edu as bczar and check whether ssh succeeds. If not fix the problem. The make script tries to copy the tar.gz files to the website using ssh.</li></ul> +<li> go to /web/users/isisbuilds/tmp/ACE_wrappers and remove the contents of this directory</li> +<li> Update the workspace with the right version tag </li> +<code> +svn co svn://svn.dre.vanderbilt.edu/DOC/Middleware/tags/ACE+TAO+CIAO-X_Y_Z/ACE ACE_wrappers<br> +svn co svn://svn.dre.vanderbilt.edu/DOC/Middleware/tags/ACE+TAO+CIAO-X_Y_Z/TAO ACE_wrappers/TAO<br> +svn co svn://svn.dre.vanderbilt.edu/DOC/Middleware/tags/ACE+TAO+CIAO-X_Y_Z/CIAO ACE_wrappers/TAO/CIAO<br> +</code> +<li> Set the needed environment variables using</li> +<code> +export ACE_ROOT=/web/users/isisbuilds/tmp/ACE_wrappers/ACE_wrappers +</code> +<li> Run doxygen --version within the shell. </li> +<li> Open up $ACE_ROOT/bin/generate_rel_manpages in your favorite editor.</li> +<li> Search for the string 'doxy_version'. </li> +<li> Check the version specified here. If it is the same as the one +you got using doxygen --version then you don't have to worry. </li> +<li> If it is different change the value of the doxy_version to the one installed on naboo.dre.vanderbilt.edu.</li> +<li> Now you are ready to create documentation </li> +<li> Do a <code>cd $ACE_ROOT</code> and then run <tt>make -f Release manpages</tt> to create the doxygen +documentation.</li> +<ul><li><b>If you can't leave the terminal window active for 6-9 hours, + consider prefixing this command with <tt>nohup</tt></b></li></ul> +<li>While doxygen churns, format a release announcement, including the +release notes gathered from developers. <a href="sample_relnotes.txt"> +You can use these as an example.</a> +<ul><li>Let <a href="mailto:schmidt@cs.wustl.edu">Doug Schmidt</a> review +these before you do anything with them.</li></ul> +<li>Check the file, generate_rel_manpages into the repository if you have made some changes to it.</li> +<li>Make sure the new version is available in Bugzilla.</li> +<ul> +<li>now we have a bczar Bugzilla user with full privileges. This bczar Bugzilla account would point to bczar user at ISIS. For example, as a new build czar, you could update the .forward file on one of the ISIS hosts, say, naboo.dre.vanderbilt.edu with your build czar email.</li> +<li>you should be able to send request through the bugzilla system to email you the password at any time to bczar@dre.vanderbilt.edu</li> +<li>here is the description of how to add a new version through Bugzilla.</li> +<li>go to any Bugzilla "Query" page, you should see a yellow box at the bottom. click "Log in" link to log in as bczar@dre.vanderbilt.edu.</li> +<li>look at the yellow box at bottom again. You will see several links following "Edit". Click on the "components" link.</li> +<li>you are then at "Select product" page. You should see a list components, i.e., ACE CIAO TAO. Click on the product you want to edit.</li> +<li>you are then at "Edit product" page. Scroll down a bit, you should see a list of all versions coming with this product. At the very beginning of the list, you should see "Edit versions" link. Click this link.</li> +<li>you should see a "Add a new version" text box and a "Add" link just above the yellow box at the bottom. Click on this link</li> +<li>you are then at "Add version of [Name of the product]" page.</li> +<li>you are able to add the new version now.</li> +</ul> +<li>Now update the documentation at + www.dre.vanderbilt.edu/Doxygen.</li> +<ul> +<li>Login to naboo.dre.vanderbilt.edu</li> +<li>su to bczar user</li> +<li>cd to directory /web/www/Doxygen</li> +<li>Create a temporary directory. eg. tmp - mkdir tmp</li> +<li>Change Directory to tmp - cd tmp</li> +<li>scp file from the download server - + scp bczar@download.dre.vanderbilt.edu:/export/www/download.dre/ACE+TAO-distribution/ACE-html.tar.bz2 .</li> +<li>Unzip and untar the files - bunzip2 ACE-html.tar.bz2;tar -xvf ACE-html.tar</li> +<li>Do cd ..</li> +<li>Create directory 'Current Version No'</li> +<li>Change directory to 'Current Version No'</li> +<li>Move contents of tmp/html to this directory - mv ../tmp/html</li> +<li>Now Change Directory - cd ..</li> +<li>Remove the already existing soflink to the "Beta" with rm Beta</li> +<li>Create softlink "Beta" linking it to new Documentation using: ln X.Y.Z/html Beta --symbolic</li> +<li>Remove the directory tmp - rm -rf tmp</lib> +</ul> +<li>Update in the autobuild archive the file configs/scoreboard/releases.xml with +the made release. This is used by the integrated scoreboard on http://remedy.nl</li> +<li>You should also the packages to the previous versions directory with the appropriate decorators. Do +this after the doxygen documentation packages are ready so that these are also archived. +<ul> +<li><code>cd /export/www/download.dre/ACE+TAO-distribution</code></li> +<li>Modify <code>/export/anduriltmp/bczar/copy_script</code> to use the correct version X.Y.Z and run it. +</ul> +<li>Mail the approved release announcement out to, at minimum the following: +<tt>ciao-users@cs.wustl.edu</tt>, +<tt>tao-users@cs.wustl.edu</tt>, +<tt>tao-announce@cs.wustl.edu</tt>, +<tt>ace-users@cs.wustl.edu</tt>, +<tt>ace-announce@cs.wustl.edu</tt>. Do this as yourself (not as bugzilla). +<b>N.B.</b> You will not be able to post to the users' lists unless you are +subscribed to them. Odds are you will not be able to post to the announce lists +at all. Ask someone else (like Doug) to do this step. +<li>When all cidlc builds are ready with the new version, login to naboo.dre.vanderbilt.edu +as bczar and run <code>./cut_cidlc.sh version-number</code> fe <code>./cut_cidlc.sh 0.6.0</code>. If this +script is not in its place, then the original is in the bin directory of the distribution.</li> +<li>Update docs/Download.html to show the new release. Make sure you refer to the +previous_versions directory, that way we can exactly track how many people download +a specific version.</li> +<li>Update etc/index.hml to show the new doxygen package you installed</li> +</ol> +</p> + + +<hr> + +<h2> Tips to being a Build Czar</h2> +<p> +1. Trust no one.<br> +2. Be careful with <a href=http://www.cs.wustl.edu/~schmidt>this +guy</a>, he is notorious in breaking builds (and fixing them as +well...Rumour has it that it's actually a super-scalar, +super-pipelined processor capable of out-of-order execution, in human +incarnation).<br> +3. Don't forgive people who break ACE :-)<br> +4. If a build hasn't run in a long time (symptoms are a "red" in the +Last Run column of the build scoreboard), delete the .disable file in +/path/to/build/directory/BUILD_NAME/ by hand.<br> +5. Think of the group who wrote the scoreboard update script, every time +you catch an otherwise not so obvious error with the help of the +scoreboard. Tell <a href="mailto:devo-group@list.isis.vanderbilt.edu"> DEVO group +</a> about it.<br> +6. Add $CVSROOT/CVSROOT/etc/FROZEN to freeze the repo <br> +7. Add names of people who need to be given permission and make sure +that you add your name so that you can see what is being checked in. <br> +8. Leave a line at the end of the FROZEN file <br> +9. Compile once on Win32, Linux and Solaris before cutting a beta.<br> +10. Trust the release script when making a release. Don't make tar +balls by hand. Make sure that the public ftp directories +(/project/beguine/ftp/pub/ACE+TAO-distribution and +/project/beguine/ftp/pub/ACE+TAO-distribution/diffs) have the right +permissions, so that the release script can copy the tar balls.<br> +11. When making a release, make sure that all the auto_compiles on +that machine (deuce.doc.wustl.edu) are stopped. Also make sure that +there is enough space in /tmp on that machine.<br> +12. When all hell breaks loose, don't wait for the nightly builds to +monitor improvement. Instead manually start the builds.<br> +13. Maintain private up-to-date workspaces for problem platforms (read +as Solaris).<br> +14. Don't hesitate to ask for help.<br> +15. When you get an account to access the cvs repo, make sure you are added to the correct groups, for example, gid=100(users),5000(doc),5002(acetaodev),5003(cvs). Otherwise you will have problem to checkout various modules.<br> +16. Install your public key to the different machines you have frequent access to avoid typing password.<br> +17. Update this page if you have any more tips for future build czars :-). This +page is in svn under <code>ACE_wrappres/docs/bczar/bczar.html</code><br> +</p> +</body> + +<body> +<Center> <h1>The Realm of the Build Czar</h1></center> +<hr> +<h2>Build Czar Arthur</h2> +<p>Many years have passes since the days of the legendary Build Czar +Arthur. His duties were given to him by the mystical Lady of the Lake, +who outlined the first responsibilities of the Build Czar.</p> +<tt> +<br> +Then bespake the Lady of the Lake,<br> +And these were the words said shee:<br> +"I knoweth of thy deeds, thou noble Arthur,<br> +but thy task hath not finished for thee"<br> +<br> +"Thou shalt feitch thy trusty steed,<br> +And cleanse thy builds againe;<br> +Then shallt thy ryde hath finnished,<br> +When new kits released thee cann."<br> +<br> +Then bespake him noble Arthur<br> +And these were the words said he:<br> +"With what weapons shallt I use,<br> +To asure these from the devil free?"<br> +<br> +Then appeered before noble Arthur,<br> +Uppon the ground a sacred scroll<br> +Conjurred by the Lady of the Lake<br> +Borne of the earth in a roll.<br> +<br> +She saies, "Clasp this to thine selfe<br> +For thee shallt find need for it.<br> +It shall keep others in the cold,<br> +Only to be ressurected when thee sees fit."<br> +<br> +"Others shall join thy person,<br> +To ryde with thee in thy quest;<br> +Thee shallt be thankful of theire help,<br> +And to alsoe hold them steadfast."<br> +<br> +"But if theire talke too lodly rise,<br> +And causeth much damage to thine cuntry,<br> +He must come forth, and make proclamation,<br> +For the next one he shall be."<br> +<br> +So hath Arthur to the Lady spoke:<br> +"For I sweare, and save my othe,<br> +While enimes and evils I seeke,<br> +I shall fight against them bothe.<br> +<br></tt> +<hr> + + +</html> diff --git a/ACE/docs/bczar/privileges.html b/ACE/docs/bczar/privileges.html new file mode 100644 index 00000000000..299b88c299f --- /dev/null +++ b/ACE/docs/bczar/privileges.html @@ -0,0 +1,63 @@ +<!-- $Id$ --> + +<html> +<head> +<title> Build Czar powers </title> +</head> +<center><h1>Powers with the Build Czar</h1></center> + <P> + This document grants extensive privileges and powers to the Czar, + but those privileges impose several responsabilities that must be fulfilled, + failure to do so may result in some form of revolution + (picture a firing squad). + </P> + + <P> + Previous generations of the honorable royal family have automated + the build process as much as possible, but all machines require attention: + the build Czar must keep a constant vigil, lest some runaway process + stops working and a critical bug scapes into the wild. + </P> + + <P>Typically a runaway build is detected because on its next + execution an email indicating that the build is + <CODE>DISABLED</CODE> + is received. + The same email is also sent when a build is abruptly terminated (for + example because the machine running the build crashed). + Most of the time, + a test is not making progress and must be terminated, + the build then runs to completion. + If the machine crashed then it is necessary to go into the build + directory and remove the + <CODE>auto_compile/.disable</CODE> + file, so the next execution can complete successfully. + Occasionally the build fails because there is a CVS conflict, + there is not enough disk space or some similar problem, + in these cases the build Czar is encouraged to request adviced + from previous generations in the royal family they will + be happy to come back from retirement to provide advice and help + if needed. + </P> + <P>The build Czar should also investigate the errors and warnings + reported by a build, + contact the person or persons responsible for the failed build and + prompt them to fix the situation. If that process above fails the + build Czar should request help from a volunteer or proceed to fix + the problem himself/herself. If there is no available + backup/volunteer and the build Czar is busy, he/she will be + forced to excomunicate the original developer and report him or + her to the highest court of the land for whatever punishment is + deemed appropriate (lashing or bone breaking where not prohibited + by law). + </P> + <P>It is extremely important to fix broken builds within the day, + otherwise the errors tend to accumulate and once the process + breaks down it is extremely hard to recover, + in other words, + the term as a build Czar can extend beyond your expectations if + the builds are not clean again. + </P> +<hr> +</html> + |