This is the preliminary design document for Developer.OpenACS.org, the hub for the developer community in the new OpenACS.org built on OpenACS v4. Please read through it and comment on it. I would appreciate any comments and feedback the community can offer.

DISCLAIMER: This is a draft. Any typos or horrible mistakes are my fault and I don't care. Because this is just a draft. Although I did look it over so I don't look like a complete fool.

talli

---

Developer.OpenACS.org

Executive Summary

Developer.OpenACS.org will be a central location for developers to access OpenACS code and documentation. It will be organized according to package and will provide decentralized administration of packages as well as a simple, consistent navigation framework.

This section has been designed with Tigris.org as its primary model. The approach is to create a consistent and standard number of elements for OpenACS module documentation, access and maintenance.

Each package subsite will have:

• Package Home
• Documentation
• Download section
• SDM page
• Individual Bulletin Board

Problem Statement

Currently, OpenACS.org is the sole location for developers to access and download the code. Since 3.2.X does not have a feature such as APM, a user downloads the entire code en masse. Documentation on the site is reasonably obvious but documentation for specific modules is difficult to find and until very recently non-interactive.

With the development and release of OpenACS 4, access to documentation according to specific package will be very important. This is because each package can be accessed and implemented independently of others. Furthermore, each package will have an owner or overseer conferred with the responsibility of maintaining the package.

The challenge with Developer.OpenACS.org will be to build a framework that provides simple and effective navigation of documentation, downloads, SDM access, patch submission and bulletin boards per package.

Central Page

The Central Page is the hub of Developer.OpenACS.org. This is the index page and from here a developer will be able to enter any package's home page with a single click. In addition, there will be a unified bulletin board which will highlight the last ten )or X number based on user's preference) posts from all the packages. There will be a link to each package's subsite. There will be a unified list of the latest submissions to the SDM. Also, there should be a link to a page containing a complete list of packages where a person can download the APM with a click.

Package Subsites

Each package will have its own subsite, preferrably with it's own URL served via virtual hosting (i.e. bboards.openacs.org, portals.openacs.org, etc.). Each package site will be organized similarly to those at tigris.org with tabs linking to pages within the packages site (see http://subversion.tigris.org). The motivation for Package Subsites it to provide consistent interfaces for the 30 odd packages and to organize the information in a coherent fashion.

Package Home: This page will be a micro version of the central page. It will feature information from each of the sections. The executive summary from the documentation page will be shown prominently so that people know exactly what the pacakge does. It will have links to the 5 most recent bboard postings. There will be a review of the most recent submissions to SDM. And of course, one will be able to download the package directly from this page.

Documentation: This page will be the entry point for documentation on each module. It will contain the executive summary of the package's documentation and links to the rest of the docs, including installation procedures, troubleshooting tips, etc. General comments will be enabled on each page. Administrators of these pages will have ETP privileges.

Download Section: This section will have links to the latest versions of APMs in CVS. It will have a very brief description of installation procedures.

SDM: This section will initially be a straight port of the SDM from a 3.x architecture to v4. See the current SDM for a sense of the functionality.

Bulletin Boards: Each package should have its own bulletin board so that all the questions and knowledge concerning it can be accessed in a single place. This is to augment the full site search with category searches. In addition, developers will have a place to seek an answer for and then ask a specific quesetion about each package. There will be a unified bulletin board elsewhere on the site where developers can access a full view of all postings.

I think that bboard per package is not a good idea. If history is any indication we'll end up with 30+ very dead bboards (that's what happened with AOLServer's bboards when they had them).

I agree with Yon, I don't think multiplying the number of boards is a good idea. Once a thread gets old it can be classified under a package heading if appropriate.

I have to disagree with "distinct presentation/personality" for each package. I believe each package is rather small piece of code that takes few weeks to few months to develop (as opposed to years as in most projects at jakarta). I also believe that after a package is done it's done and won't get a lot of additional developement (that's how it ended up for ACS 4). Therefore any additional work to "distinguish" packages, create a separate bboard for each one, create a virtual server for each one etc. might consume a large portion of the total development time.

We certainly shouldn't forbid anyone to work on making his or her package unique but I don't think it should be a policy or even that it should be encouraged.

Rafael,

Feature requests/bug reports are probably best handled through the (slightly enhanced) SDM. I guess that most modules contributions can/will be added to OpenACS CVS and SDM.

Tracking feature requests and commenting on them is already possible with the SDM.  What we definitely need is better notifications on new feature requests and bug reports, maybe one that is partially integrated with the bboard. If we can link a bboard thread to each Bug or Feature, where the bug or feature description is the first message... that would encourage ppl to write nice reports.

It might be nice to add a directlink in the module admin pages to the appropriate SDM entry.

Hey guys,

The reason I suggested having a bulletin board per package was in order to have a location for specific answers about each package to be asked. The hope would be that the person with the question would assist in organizing the knowledge that gets lost so often in the bboards.

However, I imagine that experience on the AOLserver lists has proven that this isn't the case. I also admit that often times people post to the most frequented or popular bboard, not necessarily to the most appropriate.

Since the bboards prove to be the most important source of information and full site search is not always the most effective means of getting that info, I suggest that within each package site the package maintainer (or whoever is given appropriate permission) selects threads that are relevant to that package. (Setting up internal links to other parts of the site is trivial.) Then each link gets a short description about why it is relevant for the specific package.

Taking the place of the package bboard in the Package Subsite will be a weblog for each package. The package maintainer, or perhaps team, then uses the weblog to track changes, commits, bugs, etc. Each log entry is enabled with general comments so others can comment on it.

SDM is still an issue, but I imagine it will be solved reasonably soon. Either we'll have an alpha or beta version of SDM available, or the 3.x version will be grokked to work with the 4.x system.

How does this sound?

talli