Difference between revisions of "EclipseLink/Development/FAQ"

Revision as of 12:09, 17 April 2008

This page is dedicated to Frequently Asked Questions from committers and contributors. The content is focussed on the development process, bugzilla usage, build process, and testing. The consumer facing FAQ is available here.

How do I modify the header for an existing class?

When modifying an existing class in EclipseLink a committer needs to update the header to properly reflect the change history and update the copyright information. The basic guidelines are available here

The changes can be summarized as:

1. If the copyright date range does not include the current year increase the final date or if the copyright line only has an initial date then add the current year.

2. If your company is not listed in the copyright line you need to follow one of the following two approaches to add it:

2.1. List all entities involved within the copyright notice

/*******************************************************************************
 * Copyright (c) 1998, 2008 Oracle Corporation, XYZ Inc. All rights reserved.
 * This program and the accompanying materials are made available under the 
 * terms of the Eclipse Public License v1.0 and Eclipse Distribution License v. 1.0 
 * which accompanies this distribution. 
 * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html
 * and the Eclipse Distribution License is available at 
 * http://www.eclipse.org/org/documents/edl-v10.php.
 *
 * Contributors:
 *     Oracle - initial API and implementation from Oracle TopLink
 *     committer-id - Description of change (bug ######)
 ******************************************************************************/

2.2. Add 'and others' after the Initial copyright owner

This approach may work better as the number of individuals or organizations involved increases.

/*******************************************************************************
 * Copyright (c) 1998, 2008 Oracle Corporation and others. All rights reserved.
 * This program and the accompanying materials are made available under the 
 * terms of the Eclipse Public License v1.0 and Eclipse Distribution License v. 1.0 
 * which accompanies this distribution. 
 * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html
 * and the Eclipse Distribution License is available at 
 * http://www.eclipse.org/org/documents/edl-v10.php.
 *
 * Contributors:
 *     Oracle - initial API and implementation from Oracle TopLink
 *     committer-id (XYZ Inc) - Description of change (bug ######)
 ******************************************************************************/

3. Add you committer id, company (optional), description of change, and bug # to the contributors section of the header

When to add committer id

Adding your committer id and bug number to every class for every bug fix is not a scalable solution in EclipseLink. A certain amount of judgement is required to determine if you should update the header. As a rule of thumb insert your committer id when any of the following occurs:

• New API is added to the class
• Functionality addition or modification

I created a new class, what should my Header look like

The headers for new classes in EclipseLink, that where created after the initial contribution, should not contain the line "Oracle - initial API and implementation from Oracle TopLink"

The template for newly created classes looks like this:

/*******************************************************************************
 * Copyright (c) {DATE} {INITIAL COPYRIGHT OWNER}. All rights reserved.
 * This program and the accompanying materials are made available under the 
 * terms of the Eclipse Public License v1.0 and Eclipse Distribution License v. 1.0 
 * which accompanies this distribution. 
 * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html
 * and the Eclipse Distribution License is available at 
 * http://www.eclipse.org/org/documents/edl-v10.php.
 *
 * Contributors:
 *     committer-id - initial API and implementation (bug ######)
 ******************************************************************************/

How do I check-in a change from a non-committer

When non-committers wish to submit additional functionality or a bug fix to EclipseLink they must do so using a bug. The committer who reviews and checks in the change and the corresponding test cases to resolve the bug is responsible for ensuring the Eclipse IP policy is adhered to.

The basic steps are:

1. Have the changes and the test cases reviewed appropriately by your fellow committers and/or architecture committee
2. If the size of the contribution is greater then 250 lines a CQ is required
3. Make the change with the approrpriate header modifications (see above)
4. Add the contribution to the EclipseLink IP Log