★ wanayoo — archive 1999 https://glassfish.dev.java.net/public/GuidelinesandConventions.htmlNouvelle recherche | Portail wanayoo
Login | Register
My pages Projects Communities java.net
GlassFish Project - Community Rules

| New to GlassFish | Downloads | FAQ |  Resources | GlassFish Project Home | How-Tos |

This page describes the rules and conventions for developing GlassFish.  All developers must follow the processes  described below when delivering code into GlassFish.  You can view the governance policy here.

Page Contents

Workspace Guidelines
Logging Guidelines
Coding Conventions
Commit Procedures
Quicklook Tests
Module Owners
How to Write Doc Comments
Submit a Patch

Workspace Guidelines

This clarifies the processes related to the GlassFish workspace. Please be familiar with these guidelines if you work on the workspace.

Cross-Module Coordination

  • Please use the module owner list  to communicate changes that may affect others. For example:
    • Change interfaces that other modules depend on
    • Upgrade Component to a new major version, e.g. Ant 1.4.1 to 1.5, EJB API 2.0 to 2.1
  • Before putback, you will need to ensure the complete workspace can be built. This is especially important if there are interfaces changes and multiple modules depend on the interface.

Protected Modules

  • The modules glassfish and bootstrap should not be modified without specific approval. Please email dev@glassfish.dev.java.net if you need to modify them. Please provide a brief explanation and CVS diffs.

Binary Dependencies

  • Please avoid checking in any binaries, in particular JAR files, into the workspace. We want to avoid having multiple versions of the same JAR file in the workspace.
  • Please email dev@glassfish.dev.java.net if you need to add binary dependencies. You will need to provide the URL of an official release or promoted build of the binaries and also the official version/build number of the binaries. They will be copied to a well-known location managed by release engineering and can be used by multiple modules

Packaging and DTD Changes

Please email dev@glassfish.dev.java.net if you need to:

  • Add or change the files you expose in the final product image
  • Make changes to the server configuration DTD. Note that any changes may require admin, CLI, and GUI changes.
  • Make changes to Application Server-specific deployment descriptor DTDs. Note that any changes may require DOL, deploytool, and Sun Java System Studio changes.

Logging Guidelines

The following presentation discusses the logging guidelines used in GlassFish.

Coding Conventions

All code developed for GlassFish must follow the Java Coding Conventions.

Commit Procedures

Nightly Builds

All nightly builds start everyday at Midnight PST.  Please hold commits around that time for one hour so we have time to checkout the source and start the builds on all platforms.

General Check-in Procedures

  1. Have your code reviewed by appropriate engineer(s)
  2. If you change code outside of your area, you must discuss the changes with the corresponding module owners/tech leads (see the module owner list)
  3. If you have changed only files in a single module and have not deleted files then do
    • maven clobber
    • maven checkout bootstrap build
    • maven configure-runtime
  4. If you delete or move files around or modify code in more than one module then do
    • maven clobber
    • maven checkout bootstrap-all build
    • maven configure-runtime
  5. Run appropriate set of regression tests based on the scope and riskiness of your change. You are responsible for figuring out the right set of tests to run before check-ins. Quicklook may not be sufficient for some checkins. Consult your module owner/tech lead if necessary. These are the regression tests:
    • Quicklook tests (minimum for all check-ins)
    • Developer unit tests (strongly encouraged, required for some teams)
  6. Include the following information in the commit message:
    • Description (and bugid if it's a bug fix)
    • Code reviewer(s)
    • Which tests have been run
  7. Make sure there is sufficient test coverage for your change. Consider running the developer unit tests. Is the appropriate SQE engineer aware of this change?
  8. If it's a new feature or there is documentation impact, please send email to the documentation team.

Soft Code Freeze Period

  • The goal is to fix all bugs scheduled to be fixed for the release (P1 and P2  bugs). Bugs can also be waived by the project leader if the issue is too risky to fix.
  • No new features are allowed unless they are explicitly approved by the project leader
  • All check-ins must be reviewed and approved fellow developer or module owner
  • Integrations (ORB, JAX*, MQ, etc.) must be approved by the project lead, send email to dev@glassfish.dev.java.net.

Hard Code Freeze Period

  • This period is for "surprises" only. All known bugs should have been fixed in the soft code freeze period.
  • To have a bug considered for inclusion to the release send email to dev@glassfish.dev.java.net with the word ShowStopper in the subject line
  • Follow the same steps as the soft code freeze but only showstopper bugs will be addressed
  • Any check-in has to be approved by the project leader in addition to code review
  • The project leader will respond daily with a list of approved bug fixes and waived bugs (defer until next release)

Checklist for Code Reviewers

  1. Are you the right reviewer?
  2. Can you review the code within 1 business day? (Can you find a delegate if not?)
  3. Is there a bug filed (if it's a bug fix)?
  4. Is there sufficient test coverage for the change?
  5. Are there enough comments in the code to understand the change?
  6. Is the code I18N compliant?
  7. Are there log messages for any errors? Do they have message IDs? Are they at the right level? Are they self-explanatory (i.e. not cryptic)? Does the log message have a serious performance impact?
  8. Is the code formatted with the same format as the rest of the code in the file? Are the Java coding conventions followed?
  9. Is the design sound? Does it fit in with the design of the rest of the module? Is it robust enough?
  10. Are there other related areas that need to be investigated that might need a similar fix?

Checklist for Code Submitters

  1. Is there a bug filed (if it's a bug fix)?
  2. Has the code been reviewed?
  3. Have you run all appropriate regression tests?
  4. Has information about the change been sent to the documentation writers and testers?
  5. Is there sufficient test coverage for the change? Should new unit tests be written?
  6. Has your workspace been updated recently? Are you using the right branch? Have you checked and resolved all CVS conflicts?
  7. Are there enough comments in the code to understand the change?
  8. Is the code I18N compliant?
  9. Are there log messages for any errors? Do they have message IDs? Are they at the right level? Are they self-explanatory (i.e. not cryptic)? Does this log message have a serious performance impact?
  10. Is the code formatted with the same format as the rest of the code in the file? Are the Java coding conventions followed?

Checklist for Post-review/Check-in

  1. Did you incorporate all the changes requested and get them reviewed?
  2. Did you add all of the new files to the repository?
  3. Did you update, recompile, and run the appropriate tests?
  4. Did you check in all the changes together and make sure your check-in comment contains a description, a reviewer, and the tests run? If the change spans multiple areas, it is recommended to include the list of changed files into the log message as well.
  5. If the change is a bug fix, update the issue in Bugtraq to integrated along with a pointer to the unit or Quicklook test that covers the bug.
  6. Notify testing, documentation, and any other groups of your change if it affects user functionality or a bug that was blocking them.

Quicklook Tests

Quicklook tests are breadth tests with high-level coverage of many functions in the Application Server. They are meant to give the developer a way of testing major functionality in the Application Server and of running a sanity check to ensure that nothing major is broken.

To run the Quicklook tests:

  1. Install GlassFish or get the server image (${glassfish.home}) bootstrapped using maven bootstrap, Refer to Build instructions
  2. Checkout the Quicklook tests: Once you have glassfish/bootstrap module checked out in above step, checkout Quicklook tests using "checkout-quicklook" maven goal to just checkout few required files for running quicklook tests instead of whole appserv-tests module.
    3. cd workspace (directory where you have the server code)
    cd glassfish/bootstrap
    maven checkout-quicklook
    If you want to checkout all the tests including Developers Tests, do the following.
    cvs -d :pserver:<userid>@cvs.dev.java.net:/cvs checkout glassfish/appserv-tests
  3. Environment settings and permissions:
    • Set the proper environment variables in your .cshrc, or .bat file:
    • Set APS_HOME. This is the directory where you checked out the workspace including the workspace root name (e.g. /workspace/appserv-tests)
    • Set S1AS_HOME. This is installation directory for the Application Server (e.g. /Sun/Appserver)
    • Set JAVA_HOME. This is directory where you installed JDK 5 (e.g. /Sun/jdk1.5.0_06)
    • Set MAVEN_HOME. This is installation directory for Maven 1.0.2 (e.g. /workspace/maven-1.0.2).

    On Unix:

    setenv PATH $S1AS_HOME/bin;$JAVA_HOME/bin;$MAVEN_HOME/bin;$PATH

    On Windows:

    set PATH=%S1AS_HOME%/bin;%JAVA_HOME%/bin;%MAVEN_HOME%/bin;%PATH%
  4. Modify the installation properties under ${APS_HOME}/config.properties to match your installation (e.g. admin.password, http.port, etc.)
  5. Quicklook: Run the test on Single instance Domain on Domain Admin Server (domain1). 
    % cd $APS_HOME
    % maven runtest
    Quicklook for Cluster mode: Run the test on Cluster mode Domain (which is created by using "maven configure-cluster"). This will run test on Remote instance sqe-server, created and managed by nodeagent, sqe-agent that will be automatically created by the following target. 
    % cd $APS_HOME
    % maven runtest-ee-standalone
    To run both Quicklook types above to verify your changes for all server combinations, use following command (which may take longer since its going to run the tests on both, domain1 and sqe-server as above) 
    % cd $APS_HOME
    % maven runtest-ee
  6. Open the ${APS_HOME}/test_results.html file in a browser and examine the results.

    7. Notes:

    • The default target for any build.xml file is usage. Running % ant shows a list of modules you may execute independently.
    • The runtest target specified above starts a GlassFish Server instance, starts Derby, and creates a summary report.
  7. Confirm the test count and details:
Number of test suites 27
Number of test cases 64
Sample results detailed report
Quicklook test suite details
 summary page

Module Owners

The following page lists all GlassFish module owners and the modules they own.  The owner must be notified if a change will affect hi/her module.  Any and all changes to the module are ultimately the responsibility of the owner and so must be approved by him/her. 

How to write documentation comments

See the following document for information on writing Javadoc comments.

Submit a Patch

Well-described, easy-to-apply patches are a pleasure for other developers to encounter and go a long way towards making the module or component more stable and powerful.  The first step to submitting a patch is to sign and return Sun's Contributor Agreement.  Please print this form out, fill in all the necessary detail, and return it here.

  • If you are not yet a member of GlassFish but you have mailing list access, you can post a message about your proposed patch to the project's developer mailing list. (Read more about subscribing to project mailing lists.)
  • If you are a GlassFish member, first conduct a query of the GlassFish issue database to determine whether this patch is associated with an already reported defect.
  • Also check web bugs  under category "Sun Java System Application Server/ J2EE SDK"

If your patch pertains to an existing issue, you should use the Create a new attachment link in the issue edit screen to submit your patch and the Add Comment section to post an explanatory message. (Remember that changes to issues generate automatic email messages to the issue's owner and anyone on the cc list. All those people will receive your message and a link to your patch.)

If an issue does not exist, submit your patch as a new issue, using the Patch link in the Enter An Issue section of the Issue Tracking page.  Note that you will need to update your workspace to use the latest sources, rebuild the glassfish server and we strongly encourage you to run the Quicklook tests to check that nothing is broken.  Then attach your patch file to the new issue as described here:

  1. First, make sure you are making changes in the most recent version of the source files -- for this, it is best to use CVS to check out the source (on the CVS trunk), make your modifications (but do not check them in), and then run the command:

    cvs diff -c > mypatch

    to get a context-format patch for the sources. This gives you a patch file which includes information about the version you are patching, the filenames, and the contents of the change. This is the preferred way to keep track of patches and makes it easier for others to find and test your patch.

  2. To apply a patch, go to the proper directory and run:

    patch < issuepatch.diff

  3. Always include a message with your patch with the following information:

    • A description of what problem or defect you are attempting to fix, and the steps to reproduce it, if possible.
    • A description of what the behavior should be with the patch in place.
    • A description of how the patch works, if reasonable. If a significant amount of code is involved, include within the message that you agree to let the patch be used under the applicable project license as part of the IDE's code.
    • A testcase including the jave source, scripts and documentation so we may include this test in the appserv-test/devtests testsuite.

The developer responsible for the section of code affected should either apply the patch and mark the defect (if there is one registered) as fixed, or reply with an objection if it does not seem safe, does not appear to fix the problem, or there is not really a problem to begin with. Notifications of any changes to the issues database, as well as CVS check-ins, are automatically sent to the appropriate issue assignee and cc'd to the CVS mailing lists, so you can monitor whether the patch has been applied. Be sure to subscribe to at least the CVS and issue mailing lists for the project you are working on.

If you do not know exactly how to fix a problem, but have an idea about what is causing it, you can post a message about this on the developer discussion list for other project members' suggestions or to find someone who knows how to fix it.