Thread: [smolder-commits] SF.net SVN: smolder:[880] trunk/docs
Brought to you by:
michael_peters
Menu
▾
▴
smolder-commits
|
From: <mic...@us...> - 2009-03-29 22:41:54
|
Revision: 880
http://smolder.svn.sourceforge.net/smolder/?rev=880&view=rev
Author: michael_peters
Date: 2009-03-29 22:41:49 +0000 (Sun, 29 Mar 2009)
Log Message:
-----------
removing unused docs/
Removed Paths:
-------------
trunk/docs/build_tech_spec.pod
trunk/docs/building_perl_modules.pod
trunk/docs/coding.pod
trunk/docs/configuration.pod
trunk/docs/database_support.pod
trunk/docs/db_abstraction.pod
trunk/docs/index.pod
trunk/docs/install.pod
trunk/docs/ops_backup.pod
trunk/docs/ops_upgrade.pod
trunk/docs/overview.pod
trunk/docs/release.pod
Deleted: trunk/docs/build_tech_spec.pod
===================================================================
--- trunk/docs/build_tech_spec.pod 2009-03-29 22:31:14 UTC (rev 879)
+++ trunk/docs/build_tech_spec.pod 2009-03-29 22:41:49 UTC (rev 880)
@@ -1,232 +0,0 @@
-=head1 Smolder Build System Design
-
-The Smolder build system is responsible for compiling Smolder from source
-into a form suitable for distribution and installation. It is based on
-the build system of Krang (L<http://krang.sourceforge.net>). This document
-describes the design of the build system.
-
-=head2 Background
-
-Smolder's first releases included binaries built for Fedora Core 3 on the
-i686 platform. Binaries for all CPAN XS modules as well as
-Apache/mod_perl are included in the distribution tar-ball. The
-installation system (C<smolder_install>) simply copies these binaries
-into place, sets up the database and configures Smolder using
-information provided by the user. This system works very well,
-provided you're running FC3 or a compatible system.
-
-The goal of the build system is to produce pre-compiled packages for a
-variety of platforms which will be installable via C<smolder_install>
-the same way the original FC3 package works. After this work
-is complete future development may produce native packages (C<RPM>,
-C<DEB>, etc.) as an alternative to C<smolder_install>.
-
-This system will expect the target environment to include suitable versions
-of Perl and MySQL prior to installation.
-
-=head2 Design Considerations
-
-The following factors are important to the success of the build
-system.
-
-=over 4
-
-=item *
-
-Perl
-
-Each distribution must target a particular version of Perl. This is
-necessary for the correct operation of both compiled XS modules and
-Apache/mod_perl.
-
-=item *
-
-System Libraries
-
-Each distribution will require certain system libraries, such as libgd.
-
-=item *
-
-MySQL
-
-Smolder depends on MySQL but does not include MySQL in its distribution.
-
-=item *
-
-Build Automation
-
-It must be very easy to build a distribution for a supported platform.
-
-=item *
-
-Build Testing
-
-Automated testing against all supported platforms will be useful in
-preventing broken releases.
-
-=item *
-
-Code Duplication
-
-Although each platform will have certain peculiarities, much of the
-process will be the same. This is particular true for various
-versions of a platform (FC1, FC2, FC3 for example).
-
-=item *
-
-Install-Time Activities
-
-Aside from building binaries, some install-time activities vary
-between platforms. For example, the original distribution sets up
-Smolder to start when the system boots by putting a link to C<smolder_ctl>
-in F</etc/init.d>. This may not be correct for all platforms.
-
-=back
-
-=head2 Architecture
-
-=head3 Naming Conventions
-
-Smolder distributions are created to work on a specific platform with a
-specific version of Perl. For example, typical distribution filenames
-might be:
-
- smolder-1.101-FC3-perl5.6.1-i686-linux.tar.gz
- smolder-1.101-FC4-perl5.8.2-i686-linux.tar.gz
-
-The build system will supply the distribution name (RH9, RH7.3, FC3, etc)
-and Perl will provide the Perl version and architecture using:
-
- perl -MConfig -e 'printf "perl%d.%d.%d-%s",
- (map { ord($_) } split("", $^V, 3)), $Config{archname}'
-
-End-users must choose the distribution that matches their platform,
-although C<smolder_install> will check to make sure they made the right
-reasonable choice.
-
-A special source distribution is made without building platform
-binaries. Users of this distribution will need to use the Smolder build
-system to produce a distribution they can install. The source
-distribution will be named:
-
- smolder-1.101-src.tar.gz
-
-=head3 Platform Files
-
-Each supported platform must have a directory in the F<platforms/>
-directory inside Smolder. This directory will contain at least one
-module, C<Platform.pm>, which is a sub-classes of L<Smolder::Platform>.
-This module may actually be a sub-class of another platform's module:
-ex. the platform module for FC3 could be based on the module for
-FC1.
-
-A F<README> file may also be present which will be copied as
-"F<README.$Platform>" into compiled distributions.
-
-=head2 Implementation
-
-=head3 C<smolder_build>
-
-To generate a build for a platform, the C<smolder_build> script will be
-run with a single argument:
-
- smolder_build FC2
-
-This will cause the build system to use the F<Platform.pm> module in
-platform/FC2. If all goes well the final line of output should
-be something like:
-
- Build finished, created smolder-1.101-FC2-perl5.6.1-i686-linux.tar.gz
-
-The build a distribution using a different version Perl, just run
-C<smolder_build> using the desired C<perl>:
-
- perl5.8.3 smolder_build FC2
-
-In general, building a distribution for a platform will only work on
-the platform itself. Automation using VMWare and Tinderbox may reduce
-the work associated with building and testing on each platform.
-
-=head3 Smolder::Platform
-
-The L<Smolder::Platform> module will serve as a base-class for all
-platform modules. The following methods will be available for
-overriding in sub-classes. See the module documentation in
-L<Smolder::Platform> for authoritative details.
-
-=over
-
-=item C<verify_dependencies()>
-
-Makes sure all required dependencies are in place before starting the
-build, and before beginning installation. Smolder::Platform will
-provide a way to know whether the system is being built or installed.
-
-=item C<build_perl_module($src)>
-
-Called to build a specific Perl module from the C<$src> file. The
-default implementation will simply use C<make install>, but platforms
-can override this to provide special processing for difficult modules.
-
-=item C<build_apache()>
-
-Called to build Apache. The default implementation will work the way
-the current Makefile in F<src/Apache-MOD_PERL> works.
-
-=item C<apache_build_parameters()>
-
-Override to modify the parameters passed to Apache's C<configure>
-script. This should provide an easy way to fix Apache compilation on
-most platforms.
-
-=item C<build_modperl()>
-
-Called to build Apache. The default implementation will work the way
-the current Makefile in F<src/Apache-MOD_PERL> works.
-
-=item C<modperl_build_parameters()>
-
-Override to modify the parameters passed to mod_perl's C<Makefile.PL>
-script. This should provide an easy way to fix mod_perl compilation
-on most platforms.
-
-=item C<finish_installation()>
-
-Anything that needs to be done at the end of installation can be done
-here. This is where the Redhat based modules would add a link in
-F</etc/init.d>, for example.
-
-=item C<finish_upgrade()>
-
-Anything that needs to be done at the end of an upgrade can be done
-here.
-
-=back
-
-=head2 Questions
-
-=over
-
-=item *
-
-Do we need a F<platform.conf>? This would be a configuration file
-created during build (and possibly modified during installation)
-collecting information about the platform. Could be used at run-time
-to find binaries like C<mysql>, C<tar>, etc.
-
-=item *
-
-Are there methods missing from the Smolder::Platform section that we'll
-probably need?
-
-=item *
-
-Which platforms should we target for the first release? FC3 and FC4
-are easy enough for the current team (me). Maybe using SF's build farm
-would help out with this.
-
-=item *
-
-What changes will be needed to smolder_makedist?
-
-=back
Deleted: trunk/docs/building_perl_modules.pod
===================================================================
--- trunk/docs/building_perl_modules.pod 2009-03-29 22:31:14 UTC (rev 879)
+++ trunk/docs/building_perl_modules.pod 2009-03-29 22:41:49 UTC (rev 880)
@@ -1,53 +0,0 @@
-=head1 How to add a CPAN module to Smolder
-
-This document describes how to add a new CPAN module to Smolder, or
-update an existing one. You might need to add a CPAN module when
-you're adding new functionality to Smolder. Updating an existing module
-is usually done to fix bugs or add new functionality.
-
-Follow these steps to add a new module:
-
-=over
-
-=item 1
-
-First, collect two pieces of information about the module: its license
-and what other modules it requires. If the module does not have a
-license, or the license does not allow free distribution do not add it
-to Smolder. Ensure that any required modules are already in Smolder.
-You can do this by using the F<smolder_src_dependency_check> script.
-
- $] ./bin/smolder_src_dependency_check --file src/HTML-Template-2.7.tar.gz
-
- Test::More => OK (Found in CORE)
- Digest::MD5 => OK (Found in Smolder lib)
- File::Spec => OK (Found in CORE)
- Carp => OK? (Found in Vendor lib)
-
-
-If a required module is not found, follow this same process for adding
-it to Smolder first.
-
-=item 2
-
-Copy the module distribution into the src/ directory of Smolder. This
-can be either a CVS checkout of Smolder or a source distribution (ex:
-smolder-1.011-src.tar.gz).
-
-=item 3
-
-Attempt to rebuild Smolder:
-
- make build
-
-If this completes successfully then the module is now installed into
-Smolder. Run tests and commit your changes if everything passes.
-
-=item 4
-
-If step 4 failed you may need to modify
-L<Smolder::Plaftorm>::build_perl_module() to successfully build the new
-module. If the module asks any questions during build then you'll
-need to modify the Expect calls to provide the appropriate answers.
-
-=back
Deleted: trunk/docs/coding.pod
===================================================================
--- trunk/docs/coding.pod 2009-03-29 22:31:14 UTC (rev 879)
+++ trunk/docs/coding.pod 2009-03-29 22:41:49 UTC (rev 880)
@@ -1,204 +0,0 @@
-=head1 Smolder Coding Standards
-
-The Smolder project using coding standards that are fairly common
-but mainly just because I like them :). It's not completely trivial
-and many developers will probably be involved during it's lifetime.
-To arrive at a maintainable code-base we must develop and adhere to a
-strict set of coding guidelines.
-
-=head2 Code Formating
-
-=over 4
-
-=item Indentation
-
-Code must be indented using 4 spaces, and never with hard tabs. A 2
-space indent for continued lines is recommended, but not mandatory.
-Similarly, breaking lines at 100 columns is generally prefered but not
-a requirement.
-
-Using Emacs cperl-mode, automatic indenting should be setup using:
-
- (custom-set-variables
- '(cperl-indent-level 4)
- '(cperl-continued-statement-offset 2)
- '(cperl-tab-always-indent t)
- '(indent-tabs-mode nil))
-
-Using VIM, these settings will accomplish similar goals:
-
- source $VIMRUNTIME/indent.vim
- set tabstop=8
- set softtabstop=4
- set shiftwidth=4
- set expandtab
-
-=item Perl Tidy
-
-Before any code is committed to the repository it must first be run
-through C<perltidy> (preferrably before testing since in some rare
-cases C<perltidy> can introduce bugs). The project uses the following
-C<perltidy> settings.
-
- -i=4
- -pt=1
- -ci=2
- -ce
- -bt=1
- -sbt=1
- -l=100
-
-If you use the supplied Makefile, you won't have to worry since it knows
-about these project specific settings:
-
- make tidy
-or
- make tidy_modified
-
-=back
-
-=head2 Testing
-
-=over 4
-
-=item Module Test Suites
-
-All modules will have a dedicated test suite built using L<Test::More>.
-All controller modules will have tests that use L<Test::WWW::Mechanize>.
-This test suite must be created as the module is written. Every
-significant addition to the module must be accompanied by additional
-tests in the test suite.
-
-=back
-
-=head2 Documentation
-
-=over 4
-
-=item Module Documentation
-
-All modules must have full POD documentation containing the following
-sections:
-
-=over 4
-
-=item NAME
-
-Name and short description of the module.
-
-=item SYNOPSIS
-
-This section must contain a working example of every method or
-function in the interface offered by the module.
-
-=item DESCRIPTION
-
-A general description of the purpose of the module.
-
-=item INTERFACE/METHODS
-
-A listing of each method or function in the public interface. Must
-include parameter descriptions, return values and side-effects if any.
-
-=back
-
-If appropriate, modules should include:
-
-=over
-
-=item TODO
-
-A list of known issues in the module. If you put a B<FIXME> comment
-in the code then you should list the issue here.
-
-=item SEE ALSO
-
-A list of modules related to this module.
-
-=back
-
-=item Script Documentation
-
-All command-line scripts will have full POD documentation describing
-their usage. Scripts should use L<Pod::Usage> and L<GetOpt::Long>. Scripts
-must support C<--man> and C<--help> options as shown in the L<Pod::Usage>
-documentation.
-
-=item Configuration Documentation
-
-New configuration directives for F<smolder.conf> need two pieces of
-documentation. First, they need a comment in the default
-F<smolder.conf> explaining their usage along with a reasonable default
-setting. Second, they need an entry in F<docs/configuration.pod>.
-
-=back
-
-=head2 SVN
-
-=over 4
-
-=item Commit Comments
-
-All SVN commits must come with a fully descriptive comment. These
-comments will be sent to the SVN commit mailing-list (currently
-C<smo...@li...>) and will allow
-developers to stay up-to-date with code changes.
-
-=item Commit Requirements
-
-All commited code must pass the full application test suite. This is
-defined as running F<bin/smolder_test> at the project root and finding no
-failures.
-
-=back
-
-=head2 Database Conventions
-
-=over 4
-
-=item Table Names
-
-Tables should be named with singluar nouns. For example, the table
-containing data managed by L<Smolder::DB::Project> is called C<project> not
-C<projects>.
-
-=item Join Table Names
-
-Tables that establish relationships between two tables should be named
-by combining the two table names. For example, the C<project> table is
-joined to the C<developer> table using the C<project_developer> table.
-Consider choosing the first member based on which module "owns" the
-data in the table. For example, C<project_developer> is better than
-C<developer_project> because L<Smolder::DB::Project> is responsible for
-maintaining this relationship.
-
-=item Primary Keys
-
-When an auto-incrementing integer is used for the primary key of a
-table, it should be named simply C<id>.
-
-=item VARCHAR columns
-
-All C<VARCHAR> columns must be of the maximum allowed width (255 in MySQL)
-unless there is a compelling reason to do otherwise. C<VARCHAR>s
-should be used when users will access the data in a text input through
-the UI.
-
-=item TEXT columns
-
-When a textarea is used in the UI, the column recieving the data
-should be of the C<TEXT> type. This will avoid unnecessary restrictions
-on the length of the data entered.
-
-=item SQL comments
-
-An SQL comment at the beginning of each table definition is required.
-It should identify the code module responsible for the table as well
-as any other modules which access the table. This will be helpful
-when changes are required and all table accesses must be examined.
-For example:
-
- /* The users table holds data managed by Smolder::User and
- accessed by Smolder::CGI::Login */
-
-=back
Deleted: trunk/docs/configuration.pod
===================================================================
--- trunk/docs/configuration.pod 2009-03-29 22:31:14 UTC (rev 879)
+++ trunk/docs/configuration.pod 2009-03-29 22:41:49 UTC (rev 880)
@@ -1,28 +0,0 @@
-=head1 Smolder Configuration
-
-Smolder is configured through a single configuration file called
-F<smolder.conf>. This file is stored in the F<conf/> directory inside
-Smolder. Smolder's configuration file is in the same format as Apache.
-Simple directives are set using the name and value, separated by a
-space. For example:
-
- ApachePort 8000
-
-Multiple values are separated by spaces. Example:
-
- Foo bar baz
-
-If a value contains a space, it must be enclosed in quotes (single or
-double):
-
- FromAddress "Smolder <sm...@my...>"
-
-The actual configuration directives used to configure Smolder are
-documented inside the C<smolder.conf>.
-
-B<NOTE:> After you edit F<smolder.conf> don't forget to restart Smolder
-so your changes can take effect:
-
- bin/smolder_ctl restart
-
-
Deleted: trunk/docs/database_support.pod
===================================================================
--- trunk/docs/database_support.pod 2009-03-29 22:31:14 UTC (rev 879)
+++ trunk/docs/database_support.pod 2009-03-29 22:41:49 UTC (rev 880)
@@ -1,7 +0,0 @@
-=head1 NAME
-
-Smolder Supported Databases
-
-=head1 DESCRIPTION
-
-
Deleted: trunk/docs/db_abstraction.pod
===================================================================
--- trunk/docs/db_abstraction.pod 2009-03-29 22:31:14 UTC (rev 879)
+++ trunk/docs/db_abstraction.pod 2009-03-29 22:41:49 UTC (rev 880)
@@ -1,7 +0,0 @@
-=head1 NAME
-
-Smolder Database Abstraction
-
-=head1 DESCRIPTION
-
-
Deleted: trunk/docs/index.pod
===================================================================
--- trunk/docs/index.pod 2009-03-29 22:31:14 UTC (rev 879)
+++ trunk/docs/index.pod 2009-03-29 22:41:49 UTC (rev 880)
@@ -1,95 +0,0 @@
-=head1 Smolder Documentation Archive
-
-Welcome to the Smolder documentation. This is autogenerated from the
-contents of all modules, scripts and documents in the F<docs/> directory.
-
-=head2 Admin Documentation
-
-=over
-
-=item *
-
-L<Install|docs/ops_install> - how to install Smolder
-
-=item *
-
-L<Upgrade|docs/ops_upgrade> - how to upgrade an existing Smolder installation
-
-=item *
-
-L<Backup and Restore|docs/ops_backup> - how to backup and restore Smolder
-
-=item *
-
-L<Configuration|docs/configuration> - how to configure Smolder
-
-=item *
-
-L<Script Documentation|docs/bin_inventory> - documentation for all scripts in the C<bin/> directory.
-
-=item *
-
-L<Changelog|docs/changes> - a list of changes for each version of Smolder
-
-=back
-
-=head2 User Documentation
-
-TODO
-
-=head2 Smolder Developer Documentation
-
-=over 4
-
-=item *
-
-L<Coding Standards|docs/coding> - rules for Smolder development
-
-=item *
-
-L<Module Documentation|docs/mod_inventory> - complete Smolder module API documentation
-
-=item *
-
-L<Skins|docs/skins> - How to create a Smolder skin - TODO
-
-=item *
-
-L<Adding CPAN Modules|docs/building_perl_modules> - how to add a new CPAN module to Smolder
-
-=item *
-
-L<Upgrade System|docs/upgrade_system> - How the Smolder upgrade system works.
-
-=item *
-
-L<Releasing Smolder|docs/release> - how to make a smolder distribution
-
-=item *
-
-L<Build System|docs/build_tech_spec> - How the Smolder build system works.
-
-=back
-
-=head2 Technical Reference / Design Documentation
-
-=over 4
-
-=item *
-
-L<Goals|docs/overview> - goals of the Smolder project
-
-=item *
-
-L<TODO List|docs/todo> - the current Smolder ToDo list
-
-=item *
-
-L<CPAN Module Inventory|docs/cpan_inventory> - A list of all CPAN modules included with Smolder
-
-=item *
-
-L<Database Schema Diagram|docs_database_schema.png> - graphical overview of the database - TODO
-
-=back
-
Deleted: trunk/docs/install.pod
===================================================================
--- trunk/docs/install.pod 2009-03-29 22:31:14 UTC (rev 879)
+++ trunk/docs/install.pod 2009-03-29 22:41:49 UTC (rev 880)
@@ -1,93 +0,0 @@
-=head1 NAME
-
-Installing Smolder As a Developer
-
-=head1 DESCRIPTION
-
-The purpose of this document is to walk a user through the process of
-installing a new Smolder instance. It is assumed that the user who
-installs this is (1) a knowledgable UNIX administrator, who (2) has
-root access to the machine on which he is installing Smolder, and (3) he
-has a basic understanding of what Smolder does and how it looks when it
-is working.
-
-Note: this probably won't work unless you're running on a supported
-platform. See F<docs/ops_install.pod> for the list of supported
-platforms.
-
-=head2 Smolder Install Steps
-
-=over
-
-=item 1
-
-Create a user to own Smolder instance (as root)
-
- useradd <username>
- chmod +x ~<username>
-
-=item 2
-
-Check out Smolder from SVN. The repository is located at
-
- http://svn.sourceforge.net/svnroot/smolder
-
-And instructions on how to checkout a copy of the repository are
-located at:
-
- https://sourceforge.net/svn/?group_id=161136
-
-=item 3
-
-Optionally, Upgrade/Install MySQL 4
-
-You can find binaries for MySQL 4 here:
-
- http://www.mysql.com/downloads/mysql-4.0.html
-
-Make sure you install the server, client, devel and shared packages,
-if you're using RPMs.
-
-This step is optional, because SQLite support is built-in.
-
-=item 4
-
-Build Smolder
-
- bin/smolder_build
-
-=item 5
-
-Configure Smolder. Edit F<conf/smolder.conf> to use the username you
-created in step one as C<User> and C<Group>.
-
-=item 6
-
-Build the Database.
-
- bin/smolder_createdb
-
-=item 7
-
-Run tests.
-
- bin/smolder_test
-
-=item 8
-
-Authorize user to start Smolder via SUDO (as root). Add to F</etc/sudoers>:
-
- "username ALL=(root) NOPASSWD: $SMOLDER_ROOT/bin/*"
-
-=item 9
-
-Start Smolder
-
- bin/smolder_ctl start
-
-=item 10
-
-Now visit the server in a web browser. If it works, you're done!
-
-=back
-
Deleted: trunk/docs/ops_backup.pod
===================================================================
--- trunk/docs/ops_backup.pod 2009-03-29 22:31:14 UTC (rev 879)
+++ trunk/docs/ops_backup.pod 2009-03-29 22:41:49 UTC (rev 880)
@@ -1,73 +0,0 @@
-=head1 Smolder Backup and Restore
-
-B<This functionality is currently not-finished!>
-
-Smolder includes completely automated backup and restore procedures.
-This file explains how to use them.
-
-=head2 Making a Backup
-
-To make a backup of a Smolder installation, use the C<smolder_backup>
-script:
-
- $ cd /path/to/smolder
- $ bin/smolder_backup
-
-By default this will create a Smolder Backup Archive (C<.kba>) with a
-filename of the form 'I<smolder-hostname-YYYYMMDD.kba>'. For example,
-I<smolder-valis-20031011.kba>. You can provide your own name as an
-argument to C<smolder_backup>:
-
- $ bin/smolder_backup mybackup.kba
-
-You can also create a compressed backup with the C<--compress> option,
-but beware that this can take much longer than creating an
-uncompressed backup:
-
- $ bin/smolder_backup --compress mybackup.kba.gz
-
-Full documentation for C<smolder_backup> is available by typing:
-
- $ bin/smolder_backup --help
-
-Or you can read it here: L<Smolder Backup|bin/smolder_backup>
-
-
-=head2 Restoring from Backup
-
-You can restore from a backup file using C<smolder_install>. To start,
-download the source for the version of Smolder used to create the
-backup, uncompress it and enter the directory:
-
- $ tar zxvf smolder-1.018.tar.gz
- $ cd smolder-1.018
-
-If you're unsure which version to use, you can peek inside the C<.kba>
-file with C<tar> and look at the contents of I<lib/Smolder.pm>.
-
-Then call C<smolder_install> with the C<--FromBackup> option. For
-example, to restore C<mybackup.kba> into C</usr/local/smolder> (the
-default InstallPath):
-
- $ bin/smolder_install --FromBackup mybackup.kba
-
-To restore elsewhere, include the C<InstallPath> option as with a
-normal install:
-
- $ bin/smolder_install --FromBackup mybackup.kba --InstallPath /path/to/smolder
-
-If you're restoring onto a different machine then you'll need to
-supply correct HostName and IPAddress settings on the command line:
-
- $ bin/smolder_install --FromBackup mybackup.kba --InstallPath /path/to/smolder \
- --IPAddress 127.0.0.1 --HostName localhost.localdomain
-
-C<smolder_install> will automatically call C<smolder_uninstall> if the
-target C<InstallPath> already exists, so this procedure can be used to
-restore a backup over an existing installation.
-
-Full documentation for C<smolder_install> is available by typing:
-
- $ bin/smolder_install --help
-
-Or you can read it L<here|bin/smolder_install>
Deleted: trunk/docs/ops_upgrade.pod
===================================================================
--- trunk/docs/ops_upgrade.pod 2009-03-29 22:31:14 UTC (rev 879)
+++ trunk/docs/ops_upgrade.pod 2009-03-29 22:41:49 UTC (rev 880)
@@ -1,55 +0,0 @@
-=head1 Upgrading Smolder
-
-=head2 Upgrading Smolder from a Binary Release
-
-To upgrade an existing Smolder installation, first unpack the new
-version of Smolder and enter the created directory
-
- $ tar zxvf smolder-1.013-Redhat7_3-perl5.6.1-i686-linux.tar.gz
- $ cd smolder-1.013-Redhat7_3-perl5.6.1-i686-linux
-
-Then, as root, run the Smolder upgrade script:
-
- # ./bin/smolder_upgrade
-
-If Smolder isn't installed in C</usr/local/smolder> then you'll need to
-point C<smolder_upgrade> in the right direction:
-
- # ./bin/smolder_upgrade --SmolderRoot /path/to/smolder/install
-
-
-=head1 Upgrading Smolder from a Source Release
-
-Before you can upgrade Smolder, you must build necessary packages out of
-the source release:
-
- $ cd SMOLDER_ROOT
- $ make build
-
-Once built, you need to create a distribution package:
-
- $ make dist
-
-You can then use the resulting tarball and follow the instructions
-above for Binary Releases.
-
-=head2 A Note for SVN Users
-
-First, you should only use the SVN tree if you are involved in Smolder
-development. The SVN tree is not stable for production use!
-
-If you are attempting to upgrade an existing Smolder installation from a
-SVN checkout, you must build a distribution first using
-C<bin/smolder_makedist>. If you run C<smolder_upgrade> directly from the
-SVN release, you run the risk of crucial config files being
-overwritten, along with getting your directory tree polluted with
-unnecessary SVN directories.
-
- # make build
- # make dist
- # cp smolder-versionnum-platformname-perlversion.tar.gz /usr/local/src/.
- # cd /usr/local/src
- # tar zxf smolder-versionnum-platformname-perlversion.tar.gz
- # cd smolder-versionnum-platformname-perlversion/
- # ./bin/smolder_upgrade --smolderRoot /path/to/smolder/install
-
Deleted: trunk/docs/overview.pod
===================================================================
--- trunk/docs/overview.pod 2009-03-29 22:31:14 UTC (rev 879)
+++ trunk/docs/overview.pod 2009-03-29 22:41:49 UTC (rev 880)
@@ -1,205 +0,0 @@
-=head1 NAME
-
-Smolder Overview
-
-=head1 DESCRIPTION
-
-This document describes the design goals and thoughts on a web-based repository
-of smoke test results for a software project.
-
-=head1 WHY
-
-On a recent project I spent some time working on the test framework and getting
-a dedicated server to nightly run the full smoke/regression tests. These tests
-ran and created an HTML report that was then mailed out to the all of the developers.
-Each morning was started by opening their email client and quickly reading this colorful
-and easy to see report.
-
-As the project grew, so did this report. After it reached 4986 tests the report
-was 510k of HTML.
-Even on a good machine, it took email clients a long time to render. Even when
-everything was ok (all tests passed) all developers still got this report and
-some only wanted to see it when something failed (I guess they didn't like all
-the pretty green squares).
-
-I thought, wouldn't it be nice if each developer could log into something and
-change their preference for how they want to view this report? Maybe just receive
-an email when something fails; Or just receive a link to a website where they
-can not only see the normal report, but drill down to more details; Or not receive
-anything? What if these results were kept over a period of time and then viewable
-in aggregate/summary? What if you were working on multiple projects and could do
-the same for all of them? Could this tool also handle test coverage information?
-
-=head1 GOALS
-
-=over
-
-=item *
-
-Collect test results that may come from multiple machines, from multiple
-architectures, from multiple developers and for multiple projects.
-
-=item *
-
-Allow developers to customize how they receive test reports and anything
-else that we can. I want developers to have to change as little as possible
-from the way they want things done.
-
-=item *
-
-3 levels of user permissions:
-
-=over
-
-=item * Installation Admin
-
-Create projects and add users.
-Is also a Developer.
-
-=item * Project Admin
-
-Control details of a project and add existing users to a project.
-Is also a Developer.
-
-=item * Developer
-
-Controls individual preferences that are broken out by project. This
-includes email behavior and anything else we can think of.
-
-=back
-
-=item *
-
-Show as much data as possible (or desired). This includes the following reports:
-
-=over
-
-=item 1 - By project summary of most recent test results
-
-=item 2 - Detailed view of each test result, showing all test files run and which tests passed or failed.
-
-=item 3 - Drill down from the above report to see more verbose listing of each file, or the reason for a test failure.
-
-=item 4 - Coverage report that can be drilled into
-
-=item 5 - Graphs showing progression over time of
-
-=over
-
-=item * test suite size (number of tests)
-
-=item * time to run
-
-=item * percentage of pass/fail
-
-=back
-
-=item 6 - Be able to search test results by date, architecture, and developer
-
-=back
-
-=item *
-
-Nice look a feel. Simple, but modern.
-
-=back
-
-=head1 WORKFLOW
-
-The testers would be encouraged to run their tests, automatically and periodically.
-We will provide modules to at least convert TAP to XML, and upload it to a running
-instance of smolder. Remember, the goal is to change as little as possible about their
-existing project structure, so we probably don't want to actually run their tests for
-them (since this might require other steps other than simply calling prove, etc).
-
-The user (or script) would log in and upload the XML file to smolder, which would collate
-it with the others from the same project, create the detailed reports for that run, collect
-the aggregate data into the database, generate the graphs, and then send out any desired
-emails.
-
-At any time a developer can log in and look at his project's statistics.
-
-=head1 DESIGN
-
-=head2 In General
-
-Re-use as much code as possible, and change as little about how each project's test suite
-is run. Keep to standard Perl testing practices and tools.
-
-=head2 Specifically
-
-=over
-
-=item * Use matchstick (L<https://matchstick.sourceforge.net>).
-
-This is based on the Krang (L<https://krang.sourceforge.net>)
-build/upgrade/install/run system and allows full encapsulation of the project
-so that as little effort is needed to install and run an application. The project
-is bundled with Apache (1.3.x) and mod_perl (1.29), all needed Perl modules and
-other needed binaries.
-
-Matchstick is a brand new project that needs a kick-start to get going. I think
-this would be a great way to start it.
-
-=item * Use TAP (defined in L<Test::Harness::TAP>)
-
-Maybe even use a markup language based around TAP (I<TAML>?)so that test reports include
-other information like:
-
-=over
-
-=item * Date Run
-
-=item * Time to run
-
-=item * Developer name
-
-=item * Architecture and Platform
-
-=item * Project Defined categories
-
-=back
-
-=item MVC
-
-=over
-
-=item Class::DBI
-
-=item Template Toolkit
-
-=item CGI::Application (and as many plugins as makes sense)
-
-=back
-
-=item Use L<Test::TAP::HTMLMatrix> for report #2 and #3
-
-Change look and feel with style-sheet to match look and feel of smolder.
-
-=item Use L<Devel::DProf> for report #4
-
-Change look and feel with style-sheet to match look and feel of smolder.
-
-=item Judicious use of AJAX technologies to make the user experience pleasant.
-
-Use Prototype, Script.aculo.us, and Behaviour JS libraries.
-
-=item Completely separate out the visual design into style-sheets
-
-When in doubt, put it in the style-sheet. This include images and javascript
-(behaviours). This means we can have design people not have to look at internals
-and vice versa, and makes the project completely skinnable for other organizations
-for their internal use, or so external projects can have this tool look like their
-current dev site.
-
-=item mod_auth_tkt For Auth
-
-C Module that will be built into Apache provides ticket (group) based authentication
-in a speedy manner. This will also let us limit the images (graphs/charts) that can
-be seen to only the project to which they belong and will allow authentication to
-occur at the proxy level if we ever decide to go with a built-in proxy.
-
-=back
-
-
-
Deleted: trunk/docs/release.pod
===================================================================
--- trunk/docs/release.pod 2009-03-29 22:31:14 UTC (rev 879)
+++ trunk/docs/release.pod 2009-03-29 22:41:49 UTC (rev 880)
@@ -1,76 +0,0 @@
-=head1 Releasing Smolder
-
-This document describes how to make a new release of Smolder.
-
-=head2 Pre-Release Checklist
-
-=over
-
-=item 1
-
-Make sure all changes are committed to SVN.
-
-=item 2
-
-Verify that an upgrade module has been created for this release, if necessary
-
-=item 3
-
-Update $VERSION in Smolder.pm and commit.
-
-=back
-
-=head2 Building the Source Distribution
-
-=over
-
-=item 1
-
-Make a clean checkout of Smolder:
-
-=item 2
-
-Run smolder_makedist:
-
- bin/smolder_makedist
-
-This will create 'smolder-$VERSION-src.tar.gz'.
-
-=item 3
-
-Upload the file to SourceForge and post an announcement to the Smolder
-and related (CGI::Application, perl-qa, etc) mailing lists.
-
-=back
-
-=head2 Building Binary Distributions
-
-On each supported platform perform these steps:
-
-=over
-
-=item 1
-
-Download the source distribution and untar it.
-
-=item 2
-
-Run smolder_build, supplying the plaform name if necessary:
-
- bin/smolder_build
-
-=item 3
-
-Run smolder_makedist:
-
- bin/smolder_makedist
-
-This will create 'smolder-$VERSION-$PLATFORM-$PERL-$ARCH.tar.gz', which
-is a binary distribution of Smolder.
-
-=item 4
-
-Upload the file to SourceForge and post an announcement to the Smolder
-mailing lists.
-
-=back
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
Thanks for helping keep SourceForge clean.
X