directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <>
Subject [Directory Wiki] Update of "ProjectWebSite" by CKoppelt
Date Sun, 04 Feb 2007 17:48:49 GMT
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Directory Wiki" for change notification.

The following page has been changed by CKoppelt:

The comment on the change is:
out of use

- #pragma section-numbers off
+ deleted
- = Project Site =
- == Impetus ==
- For some time we have had problems distributing work among our selves and
- attracting new developers.  The learning curve is massive and there is no
- beacon to guide new comers so developer retention problems exist.  We need
- tools to help overcome these barriers.  A home page or site for the project
- was one of the main tools we agreed would aid in solving these problems.
- We came to a rapid conclusion that we need to build a website with various
- developer resources before continuing with any further development.  We need
- to state who we are, what we wish to achieve and provide a clear roadmap with
- milestones and guides for developers interested in contributing to the development
- of various subprojects.  This is absolutely paramount to our success.
- Next we need to better utilize the resources available to us here in the incubator.
- This includes the wiki, JIRA, subversion and other tools to better manage the
- project in general.  We would like to make it easier for developers to find things
- to do for the project without worries about duplicating efforts.  We need to find
- a better means to divide labor.  This mostly entails agreeing upon a design, carving
- out interfaces and coding to those interfaces after developers have chosen their
- niches hence the parts of development they would like to take on.  We would like to
- maximize collaboration and peer review to capitalize on the entire community's
- knowledge without holding back individuals that would like to grok the code at their
- own pace with a minimum of coordination overhead.  Integrating these tools together
- in one contiguous site increases the chance off using these tools.  Everything then
- is managed through one central place.
- The site need not be complete and will gradually progress as does the project.  However
- some things need to be defined in advance.  That's what this document is for.
- == Site Sections ==
- The site's breakdown will naturally follow the subproject structure.  At this point
- we have a few major categories and a few subcatagories:
-    * sitedocs
-    * resources
-    * tools
-    * naming
-    * asn1
-    * janus
-    * ldap
-       * eve
-       * common
-       * clients
-       * installer
-       * tests
- The navigation should allow users to jump from section to section and from deeper nested
subsections to top sections.  A navigation menu to the left hand side should use folding
- menus to guide the user through the site.  Furthermore the navigation can correspond one
- to one with the layout of the repository.  If this pattern is maintained along with others
- then tools and scripts can be built to automatically generate and update the site without
- human intervention or a minimum of it.
- === sitedocs ===
- The sitedocs section should describe how to modify the site - basically what we are trying
- to establish in this document.  This obviously will not be the complete set since various
- projects, subprojects and so on will have their own documentation sets.  This project simply
- stores the top level documents and the code/configuration for the site document generation
- system.  This major section of the site describes how to build the site and alter the site
- to include your project in it etc.
- Here's a list of recommended items found here:
-    * Howto build the site
-    * Howto deploy the site
-    * Howto manage documentation in general
-    * Resources and examples on using sdocbook, xdocs and hooking it into the site
-    * Site structure and code used to build it
-    * Any custom tools used for generating documentation are described and documented here.
- ==== Howto build the site ====
- The sitedocs sub-project deals with the top-level site documentation. When building the
web site, documentation from sub-projects is generated and aggregated to build the whole site.
- Building the site is a simple as running:
- {{{
- maven site
- }}}
- from the sitedocs sub-project.
- This process will generate the HTML documentation into the target/docs folder. This documentation
then needs to be deployed to the web server.
- ==== Howto deploy the site ====
- Currently as a podling the Directory Project's resources are managed under the Apache Incubator.
- The website is no exception.  The specific incubator module used is the '''incubator-directory'''
- CVS module.  Check it out like so:
- {{{
- cvs -d co incubator-directory
- }}}
- This module contains a content directory: '''www'''.  The final content under '''www'''
is served
- up by the Apache servers.  The module's '''www''' folder is checked out daily into the following
- directory on
- /www/
- So all we have to do is generate the site out of our subversion
- working directory and copy the Maven generated content into the
- '''www''' folder of the CVS working copy for the incubator-directory
- CVS module.  That's a mouth full.
- Once the generated content is copied, the changes are committed.  Then
- deployers should ssh into and cd to the
- '''/www/''' to do an update like so:
- {{{
- cd /www/
- cvs update -d
- }}}
- === resources ===
- Describes the various resources for this TLP to be.  Things like JIRA, wiki and other
- resources as well as various top level guides can go under here like coding standards
- and agreed upon development methodologies.
- Each subsection may have its own specific resources like, FAQs, HOWTOs, and
- user/developer guides.
-    * Cover all repository issues with a subversion repo faq/howto
- === naming ===
- TBC by naming peeps
- === asn1 ===
- TBC by asn1 peeps
- === janus ===
- TBC by janus peeps
- === ldap ===
- Here we need several guides and resources but I've focused here more on the Eve subsection:
-    * Goals/Objectives
-    * Server features
-    * Developer Guides
-       * General Guidelines
-       * Getting Started
-       * Dependent Technologies
-       * High Level Server Design
-       * Detailed Design
-       * Component Registry (Listing)
-    * Resources
-       * LDAP RFC documentation
-       * LDAPBIS Drafts
-       * Relavant X.500 Notes
-       * SEDA Documentation
-       * Avalon Resources
- === Tools ===
- What are we going to use to get us there?  Obviously we're going to leverage Maven
- to build the site using markup like xdocs and sdocbook to build out the site navigation
- and content.
- === Maven ===
- We use maven but how? Perhaps we need to do some jelly customization or write a plugin.
- We definately want a plugin for generating component information for each component to
- use for the component registry.
- === Jelly ===
- Need to customize maven with jelly.  Code to build the project site and subproject sites
- in a project to subproject dependency tree and gather the generated sites will require some
- custom code.
- Any new maven plugins will require some jelly.
- === XSLT ===
- We can use XSLT to transform lots of xml we have into a presentable form.
- == Patterns and/or Approach ==
-    * each site section or subsection down to the lowest layers keeps a maven project for
generating its own site
-    * upper layers delegate to lower layers to generate their sections of the site
-    * use xdocs in each [sub]section for navigation and simple documentation
-    * use sdocbook if necessary in respective regions for larger guides
-    * kicking off a site build results in a recursive site generation
-    * goals in top level can be used to assemble the site be aggregating the individual generated
[sub]sections sites
- === Maven plugin ===
- There is alot of cool stuff we can do here with a custom plugin and the
- various tools at our disposal to build the site or generate component docs
- and or distros requiring custom stuff.
-    * use a custom maven plugin to build component subproject documentation from the Maven
POM and the Merlin descriptors
-    * use subversion properties on various directories and or files to effect the manner
in which documentation is generated.  We can flag components as components and differentiate
projects that way or we could use the etc.
-    * between subversion properties and we can define plugin specific
properties that effect the way the site is generated by our plugin.

View raw message