The new and all improved Apache DB Site -- How it works ======================================================= Henning Schmiedehausen - henning@apache.org - 2005-08-01 If you have questions about the build process of the db site, please ask on the general mailing list at general@db.apache.org. The ultimate decision on who might change information on the site or what is put in the site module has the Apache DB PMC, which you can reach at pmc@db.apache.org. Do not ask questions about the db site on the Apache general mailing list or the httpd mailing list. Those folks can't help you. :-) Overview of DB site maintenance --------------------- 1. Check out the site module from the svn repository. 2. Modify the files in xdocs or the top level project files as required. 3. Run maven in the root directory to build the site locally. 4. Review your changes by opening target/docs/index.html . 5. When you are satisfied with the changes, check them into svn. 6. Deploy the site by invoking "maven site:deploy". See the following sections for details. Regenerating the site --------------------- Unlike the build process up to now, you don't need to check out all of the DB projects any longer. If you want to rebuild the site, you just check out the "site" module from the repository and run maven in its root directory. This will build the new site locally. Please use maven 1.0.2. You can deploy the site by executing "maven site:deploy". The site will not be deployed directly to the db.apache.org server but to a staging server running on people.apache.org and will be updated to the main server every two hours. In order to deploy the site, you must upload your ssh key to people.apache.org. These instructions tell how to set up an ssh key and start the agent: http://www.cs.utk.edu/~england/ssh.html If you want to try out immediately after deployment, add a Proxy setting to your browser using 209.237.227.195:80 and access db.apache.org normally. Adding a PMC member to the site ------------------------------- The db-site module abus^Wuses the project.xml tags for listing the PMC members. If you want to add a new PMC member, follow the pattern of the other PMC members in project.xml in the root and rebuild and deploy the site. Please be aware of the following things: - The list should be kept in natural (alphabetic) order of the Apache committer ids - The PMC members should keep the The Apache Software Foundation line. If you don't want this, don't use an organization field. - The PMC related mail address should be your apache.org mail address. - The Roles field is intended for your PMC role. If you don't care, just leave it PMC Member. If you want to show for which projects you are on the PMC (which will in turn users and committers help to find out which projects are represented on the PMC), please add your project(s) to the roles field. - If you are the PMC chair, please change your role accordingly. :-) Adding a new project to the site -------------------------------- The db-site module uses maven to collect information about the projects and build the web pages. For this, it tries to read the POM (project descriptors, "project.xml") files for all the sub-projects in the db project. From these files is e.g. the list of developers visible on the whoweare.html page built. The db-site no longer builds from the "live" POMs of the sub-projects. Main reason is that it was very difficult and cumbersome to add new projects to the site, especially if they don't use maven as their build tool. For each sub-project, its POMs are kept in the projects/ subdirectories inside the db-site module. This means, that changes in the POM of your project (e.g. new developers) are not immediately reflected on the site. Please update the POMs inside the db-site module from time to time so that they don't get stale. - If you build your project with maven Very simple: create projects/ and copy your project.xml file in there. If you inherit from some other file (e.g. torque does this: project.xml inherits from project-base.xml), don't forget to copy that file, too. You are done. Rebuild the site and deploy it. - If you don't build your project with maven Please take some time to create a skeleton POM for your project and put it into the projects/ subdirectory as project.xml. This POM does not need to be complete or working, it is only used to keep the information about your project which is needed to build the site. If you try to hack your page links into the html files, they will be gone by the next time anyone updates the db-site module. This is a sample pom file which you can use as a starting point for your project: 3 your project name your project id your project url your repository view url *** connection to check out anonymously from your repository *** connection to check out anonymously from your repository *** *** myproject User List myproject-user-subscribe@db.apache.org myproject-user-unsubscribe@db.apache.org http://mail-archives.apache.org/mod_mbox/db-myproject-user/ [repeat the block for multiple lists] *** John Doe johndoe johndoe@spamfix.org ACME Inc. Java Developer +2 [repeat the block for multiple developers] All elements marked with "***" are optional. If you don't give information here, the corresponding fields will not show up in the db-site pages. Please _KEEP_ the surrounding tags! (e.g. don't remove the tag, even if you don't have a mailing list yet). Examples for working skeleton POMs are in the projects/ddlutils and projects/derby subdirectories.