The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Cvs-Brancher-1.00
/ branch.pl

NAME

branch.pl - Branches a cvs modules & schedules a build operation via 'at'

SYNOPSIS

branch.pl modulename MM/DD/YY HH:MM [ options ]

Options:
  -b, --branch_name=string      Name of branch
      --build_script=string     Name of script in module to invoke
  -c, --co_dir=string           Name of checkout directory to use
  -d, --cvs_root_dir=string     CVS ext/pserver string
  -D, --debug=integer           Prints debug messages
      --die_on_fail             Abort on merge error or deploy anyway
  -h, --help                    Prints a brief help message
  -H, --helplong                Prints a long help message
      --logfile=string          File to direct stdout/stderr of at-job
      --man                     Prints a manual page (detailed help)
      --notify_to=string        Address to send notifications to
      --notify_from=string      Address to send notifications from
  -q, --quiet                   Keep cvs output somewhat quiet
      --smtp=string             Name of the SMTP server to send to
  -V, --version                 Prints the version and exits
  -Q, --very_quiet              Keep cvs output very quiet
  -w, --working_area=string     Temporary dir for doing checkout work

DESCRIPTION

branch.pl establishes a tagged branch in a CVS module and schedules a merge and build to occur at a later date. It is intended to be used in conjunction with scheduled_build.pl for doing scheduled automated merge, build and deployments. You might use it to roll out website changes at odd hours, such as posting a press release in time for the start of the business day on the east coast, or to roll out cfengine changes to a data center during the night, to minimize the impact of downtime.

Once run, you can check out the branch and make any changes required. Check the changes back in to assure they'll be deployed correctly.

You can review the queued jobs via 'atq' or 'at -l'. Jobs can be removed via 'atrm' or 'at -rm'. See your 'at' documentation for more details.

If you need to reschedule a deployment, take note of the branch name and other options, remove the queued job, and then add a new job at the new time. Note that the branch name will continue to have the _original_ release date/time in its name, but that's okay; it's only there for informational purposes.

OPTIONS

-b, --branch_name

This option allows overriding of the name to use when tagging the branch. The default is to name it 'Scheduled_release_MMDDYY_HHMM'. If you choose to override it, note that the ':' and '/' characters should not be used and will be stripped out.

The branch_name is used both for the tagging of the cvs module and for naming checked out directories, so if you choose to override it, do so with care. You may want to override this if you wish to use a different tag naming scheme.

This is used as the argument to scheduled_build.pl.

--build_script

The name (and path if necessary) to the script to be run at the scheduled time. For example, this script would attempt to rebuild the website and return an error code if there is a problem.

This parameter is passed to scheduled_build.pl.

-c, --co_dir

This allows overriding the checkout directory name. By default this will be set to 'modulename_MMDDYY_HHMM-branch'. If you choose to override it, note that the ':' and '/' characters should not be used will be stripped out.

This directory is used temporarily to checkout the HEAD in order to create the branch. You probably will never need to override this.

-d, --cvs_root_dir

This option allows specification of the pserver or ext string to use for CVS checkouts. This is the same as the contents of the CVS/Root variable in your checked out CVS module. It is passed to the cvs commands as `cvs -d $cvs_root_dir command ...`

If this is not set, the value of the $CVSROOT environment variable will be used.

The value of this option is also passed to scheduled_build.pl.

-D, --debug

Prints debug messages. Specify a number from 0 (none) to 5 (all) to indicate the verbosity of debug messaging. Also note that verbosity of the invoked cvs commands can be controlled via the --quiet and --very_quiet options.

--die_on_fail

Normally, scheduled_build.pl will detect when a merge has failed and re-try without doing a merge. This option suppresses this behavior so that the program simply terminates on a merge problem.

This parameter is passed to scheduled_build.pl.

-h, --help

Prints a brief help message

-H, --helplong

Prints a long help message

--logfile

Filename for putting the at-job's stdout and stderr streams. This will be in addition to any emails sent. By default it is set to /dev/null. Setting this can be useful for debugging purposes.

--man

Prints a manual page (detailed help)

--notify_from

This is the email address that messages should be marked as being from. This controls what appears in the From field of the email messages.

--notify_to

This allows specifying where email notifications should be sent. For example, this can be set to send messages to a mailing list that interested watchers can subscribe to as they wish.

-q, --quiet

This passes the '-q' option to cvs, which causes cvs to be 'somewhat quiet'. From the cvs manpage: "informational messages, such as reports of recursion through subdirectories, are suppressed."

This parameter is also passed to scheduled_build.pl.

--smtp

Name of the SMTP server to send email notices. This is required by Mail::Sender; see its manpage for more details.

This parameter is also passed to scheduled_build.pl.

-V, --version

Prints the version and exits

-Q, --very_quiet

This passes the '-Q' option to cvs, which causes cvs to be 'very quiet'. From the cvs manpage: " the command will generate output only for serious problems."

This parameter is also passed to scheduled_build.pl.

-w, --working_area

This is the directory that the system should use for placing checkouts of the CVS modules. Note that in cases of merge failures, branches will be left in this directory, so give thought to sizing the file system this is on to permit multiple copies of the cvs module to exist here.

The value of this option is also passed to scheduled_build.pl.

See branch.pl -h for a summary of options.

PREREQUISITES

This script requires the following Perl modules:

Carp, Pod::Usage, Getopt::Long, File::Basename, File::Copy, File::Find, File::Path, File::Spec, Cvs::Brancher

SCRIPT CATEGORIES

CPAN/Administrative

BUGS

The system has a granularity of 1 minute since 'at' has a 1-minute granularity. It's not expected that this will pose a problem in practice, although note that if you run this script a couple times in quick succession, it won't behave properly.

The date syntax MM/DD/YY is used, although YYMMDD would be preferred. This limit is due to the way 'at' works on the developer's machine.

VERSION

1.00

Distributed as part of Cvs-Brancher.

SEE ALSO

perl(1), tgen , cvswebsite

AUTHOR

Bryce Harrington <bryce@osdl.org>

http://www.osdl.org/

COPYRIGHT

Copyright (C) 2003 Bryce Harrington. All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

REVISION

Revision: $Revision: 1.12 $