Index: openacs-4/packages/acs-core-docs/www/xml/kernel/apm-requirements.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/apm-requirements.xml,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/xml/kernel/apm-requirements.xml 24 Dec 2001 19:31:43 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/xml/kernel/apm-requirements.xml 2 Feb 2002 03:47:32 -0000 1.3 @@ -1,5 +1,5 @@ - -ACS 4 Package Manager Requirements + +OpenACS 4 Package Manager Requirements by Bryan Quinn and Todd Nightingale @@ -9,7 +9,7 @@ Introduction -The following is a requirements document for the ACS Package Manager +The following is a requirements document for the OpenACS Package Manager (APM), version 4.0 (APM4). APM4 offers a superset of APM v3.3 functionality with the following specific enhancements: @@ -29,7 +29,7 @@ To differentiate these new requirements from the requirements of version 3.3, all requirements new in v4 are prefaced with the number -4. +4. We gratefully acknowledge the authors of APM 3 for their original design documentation which suggested these features, as well as the influence of the @@ -49,16 +49,16 @@ system, content management system, etc. For such applications and subsystem components, modularity - or the degree to which a component can be encapsulated and decoupled from the rest of the system - is of great value. -Thus the ACS Package Manager (APM) was created to allow website components, +Thus the OpenACS Package Manager (APM) was created to allow website components, or packages, to be added, removed, and upgraded easily, with minimum disturbance to the rest of the system. This allows site owners to steadily offer users new and improved services, and also allows programmers to quickly -and easily distribute their ACS components in a standardized manner to other -ACS sites. +and easily distribute their OpenACS components in a standardized manner to other +OpenACS sites. In general terms, a package is a unit of software that serves a single -well-defined purpose. The ACS Package Manager (APM) provides a mechanism for -packaging, installing, and configuring ACS software in a consistent, +well-defined purpose. The OpenACS Package Manager (APM) provides a mechanism for +packaging, installing, and configuring OpenACS software in a consistent, user-friendly, and subsite-aware manner. @@ -67,14 +67,14 @@ System Overview -The ACS Package Manager (APM) consists of: +The OpenACS Package Manager (APM) consists of: -A standard format for APM packages including: +A standard format for APM packages including: -Version numbering, independent of any other package and the ACS as a +Version numbering, independent of any other package and the OpenACS as a whole Specification of the package interface @@ -87,7 +87,7 @@ -Web-based tools for package management: +Web-based tools for package management: Obtaining packages from a remote distribution point @@ -101,7 +101,7 @@ -Configuring packages (obsoleting the monolithic ACS configuration +Configuring packages (obsoleting the monolithic OpenACS configuration file) Upgrading packages, without clobbering local modifications @@ -112,13 +112,13 @@ -A registry of installed packages, database-backed and +A registry of installed packages, database-backed and integrated with file system-based version control -Web-based tools for package development: +Web-based tools for package development: Creating new packages locally @@ -128,13 +128,13 @@ Uploading packages to a global package repository on the web Use of these tools should be safe, i.e. installing or removing a package -should never break an ACS installation +should never break an OpenACS installation -Web-based tools for package configuration: +Web-based tools for package configuration: The ability to change package parameter values on-line through a simple @@ -159,43 +159,43 @@ overlap: -Developers (referred to as 'the developer') use +Developers (referred to as 'the developer') use the APM to create a software package for distribution and use the procedural API for direct control of the APM system. -Site-wide administrators (referred to as 'the -administrator') use the APM to install packages for their ACS instance, +Site-wide administrators (referred to as 'the +administrator') use the APM to install packages for their OpenACS instance, and optionally make them available to sub-sites. -Sub-site administrators (referred to as 'the +Sub-site administrators (referred to as 'the sub-admin') use an administration interface to configure and enable packages for their sub-site. -Initial Package Development +Initial Package Development -David Developer writes a piece of software used to do -knowledge management (km) for the ACS. He distributes his data model, +David Developer writes a piece of software used to do +knowledge management (km) for the OpenACS. He distributes his data model, procedure code, UI pages, and his documentation according to the APM specification. He splits the documentation and the code into sub-packages, and creates a KM installation-chain to install both with the APM developer -UI. Noting that his software was built with Patricia -Programmer's Super Widget toolkit, he specifies that as a +UI. Noting that his software was built with Patricia +Programmer's Super Widget toolkit, he specifies that as a dependency. Moreover, since this package is capable of being used at the sub-site level, David configures this option in the package. When the package development is complete, David uses the APM developer UI to construct a distribution file. He assigns it a version number, 1.0, and makes the package -available for download at the ArsDigita package repository. +available for download at the OpenACS package repository. -Initial Package Installation +Initial Package Installation -Annie Admin learns of David's KM system by browsing -the ArsDigita package repository. Annie Admin uses the APM administrator UI +Annie Admin learns of David's KM system by browsing +the OpenACS package repository. Annie Admin uses the APM administrator UI on her system. She selects to install a package from a URL and types the URL displayed on the system. The APM automatically downloads the package. The dependency checker notices that Patricia's Super Widget toolkit is required, so it warns Annie of this. Annie selects an option to find a -package that satisfies the dependency at the ArsDigita APM repository. The +package that satisfies the dependency at the OpenACS APM repository. The APM informs Annie that it can download and install Jim's Super Widget toolkit. Annie confirms this option. After successfully installing Jim's toolkit, Annie proceeds to install David's KM system. The data model is @@ -207,13 +207,13 @@ are initialization routines, she must restart the server for the package to be ready for use. Annie restarts the server. -Initial Subsite Use of Package +Initial Subsite Use of Package Annie Admin decides to make the KM module available only to a particular -sub-site type on her ACS system, and not others. She specifies this option +sub-site type on her OpenACS system, and not others. She specifies this option using the Sub-site type UI (not part of APM). -Annie Admin notifies Sally SubAdmin by e-mail that a new +Annie Admin notifies Sally SubAdmin by e-mail that a new package is now available for use. Sally goes to her sub-site /admin page and sees that a new entry, KM, is available. Sally clicks on it and finds links to the installed KM documentation and to the web based configuration utility. @@ -222,7 +222,7 @@ the package, Sally decides to change some parameters using the SubAdmin UI. These changes take effect immediately, without any server restarts. -Upgrade Process +Upgrade Process Sally SubAdmin finds a bug in the KM system and sends a report to David Developer. David reads the bug report and verifies that the bugs are present @@ -239,9 +239,9 @@ Once Annie upgrades the package, the new version starts working immediately in Sally's sub-site. -Procedural API +Procedural API -Danielle Developer wants her software to perform +Danielle Developer wants her software to perform different actions depending on what version of another package is installed. She uses the APM procedural API to check if KM version 1.0 is installed or version 1.1. Based on the results of this procedural call, the software @@ -268,30 +268,30 @@ -4.500.0 Package Identification +4.500.0 Package Identification (All of these items are entered by the developer using the developer UI.) -4.500.1 A human readable package key that is guaranteed -to be unique to the local ACS site must be maintained by the APM. For +4.500.1 A human readable package key that is guaranteed +to be unique to the local OpenACS site must be maintained by the APM. For example, "apm." -4.500.5 A package id (primary key) that is guaranteed to +4.500.5 A package id (primary key) that is guaranteed to be unique to the local site must be maintained by the APM. For example, "25." -4.500.10 A package URL that is guaranteed to be unique +4.500.10 A package URL that is guaranteed to be unique across all sites must be maintained by the APM. The package URL should point to a server that allows download of the latest version of the package. For -example, "http://software.arsdigita.com/packages/apm.apm." +example, "http://openacs.org/software." -4.505.0 Version Identification +4.505.0 Version Identification (All of these items are entered by the developer using the developer UI.) -4.505.1 A version id (primary key) that is guaranteed to +4.505.1 A version id (primary key) that is guaranteed to be unique to the local site must be maintained by the APM. -4.505.5 A version URL that is guaranteed to be unique +4.505.5 A version URL that is guaranteed to be unique across all sites must be maintained by the APM. The version URL should point to a server that allows download of a specific version of the package. @@ -311,14 +311,14 @@ -4.400.0 Packages Status Predicates +4.400.0 Packages Status Predicates -4.400.1 Given defining information such as a package URL, -the APM API can return the status of the package on the local ACS +4.400.1 Given defining information such as a package URL, +the APM API can return the status of the package on the local OpenACS instance. -4.410.0 Sub-site Procedures +4.410.0 Sub-site Procedures -4.410.1 After a package has been installed at the +4.410.1 After a package has been installed at the site-wide level, the system API will provide means to check for package presence, creation, enabling, disabling, and destruction on a subsite. -4.415.0 Parameter Values (replaces ad_parameter) +4.415.0 Parameter Values (replaces ad_parameter) -4.415.1 The system API shall allow subsite parameters for +4.415.1 The system API shall allow subsite parameters for an installed package to be set by either site-wide administrators or sub-site admins. The subsite parameter can be set to be non-persistent (but default is to survive server restarts). The subsite parameter can also be set to only take effect after a server restart (default is immediate). -4.415.5 Parameters for a given subsite and package can be +4.415.5 Parameters for a given subsite and package can be returned by the system API.