CVS Branches and Labels
The NetBeans source is organized in terms of
CVS branches and labels. Currently the
interesting ones are:
- The CVS trunk. Now and in the future,
new functionality that is reasonably stable (does not break anything
else) goes into the trunk. This code is used to make regular daily development builds.
- Q-Build branches. Roughly once in two weeks a development build is made which
has been vetted for quality. Each such "Q-build" gets its
own CVS branch, which usually diverges from the trunk in only a few files which
needed to be patched to fix high-impact bugs.
- NetBeans Release 6.0: the CVS branch
release60 holds sources
for the NetBeans 6.0 stable release.
- NetBeans Release 5.5: the CVS branch
release55 holds sources
for the NetBeans 5.5 stable release.
- NetBeans Release 5.0: the CVS branch
release41 holds sources
for the NetBeans 5.0 stable release.
- NetBeans Release 4.1: the CVS branch
release41 holds sources
for the NetBeans 4.1 stable release.
- NetBeans Release 4.0: the CVS branch
release40 holds sources
for the NetBeans 4.0 stable release.
- NetBeans Release 3.6: the CVS branch
release36 holds sources
for the NetBeans 3.6 stable release.
- NetBeans Release 3.5: the CVS branch
release35 holds sources
for the NetBeans 3.5 stable release.
- NetBeans Release 3.4.1: the CVS branch
release341 holds sources
for the NetBeans 3.4.1 stable release.
- NetBeans Release 3.4: the CVS branch
release34 holds sources
for the NetBeans 3.4 stable release.
- Sun ONE Studio (formerly Forte for Java) 4.0: the CVS branch
orion_fcs is used
for Sun's Sun ONE Studio (Forte for Java) Community Edition 4.0. This branch is almost identical
to release33 (below) for most modules.
sierra is used for 4.1.
- NetBeans Release 3.3.x: the CVS branch
release33 holds sources
for the NetBeans 3.3.x stable releases.
- Sun's Forte for Java 3.0: the CVS branch
pilsen holds sources
for Sun's Forte for Java Community Edition 3.0. For most modules, this
is based off of NetBeans Release 3.2 (below) with no or very limited changes.
For web, j2eeserver, and logger modules
this branch contains distinct lines of development.
- NetBeans Release 3.2.x: the CVS branch
release32 holds sources
for the NetBeans 3.2 and 3.2.1 releases.
- NetBeans Release 3.1: the CVS branch
release31 holds sources
for the 3.1 release of NetBeans.
- NetBeans Release 3.0: the CVS branch
stable30 holds
the source for a former stable NetBeans release. It is based off
of the postfcs branch, below.
- Sun's "Boston" branch: the CVS branch
boston was
reserved for stabilization of the FFJ 2.0 release.
- Sun's post-FCS branch: the CVS branch
postfcs is
reserved for the code line used for the 1.0.x versions of
FFJ, including a number of module updates.
-
gandalf branch represents the 1.0 released IDE,
pre-updates.
General principles of using branches in CVS:
- The CVS trunk (main version numbers, such as
1.23)
should be used for ongoing development of the IDE. Code checked into
the trunk should be reasonably stable (i.e. it should compile and at
runtime should not cause the IDE to be unusable, especially in terms
of interfering with other modules or components of the IDE). It need
not be perfect.
- Branches may be created by developers for purposes of
checkpointing experimental code which is not expected to be stable for
a long period of time. These branches may be created as needed,
possibly on a per-module basis. Module pages should document branches
they are using.
- Stabilization branches, which should be documented here, and are
used to stabilize the entire IDE in preparation for an official
release of some sort. Commits to these branches should be to fix
important bugs, not to add new functionality; and such bugfixes should
be also applied immediately to the trunk (assuming they apply). The
NetBeans team may create such branches and other parties who are
interested in producing a release may also create them. Since
stabilization branches exist in the public repository, anyone can take
advantage of testing and fixes done on these branches.
If you get access to the CVS server
for checkin, please make sure you understand what the different branches are
being used for, and check in onto the appropriate branch, with an appropriate
amount of pre-checkin testing.
If you are contributing a new module to the NetBeans source
repository, though, you are of course the owner of this code and can
decide how it should be organized - in terms of whether and how to use
branches, who should have write access to the source code, etc.
People who wish to make new branches in CVS (especially for holding experimental
codelines) should first understand the issues involved in this, and what to
do to make the branching be safe and effective. For this reason, there is a
paper on branches in CVS.
Naming Conventions
Branches in CVS should be named as follows: if they represent a
stabilization branch, they should be named with
release
followed by the expected IDE version number of the release, sans
punctuation, e.g.
release31 for the 3.1 release.
Experimental branches should be named according to the affected module
(if applicable), a description of the implemented feature or reason
for branching, and an associated Issuezilla issue number: for example,
java_new_parser_26113. All branches should be rooted
from an existing non-branch tag; this could be a build tag, but
recommended is to create a special root tag ending in
base, for example
release31_base. This can
be useful for subsequent merging.
Build tags in CVS for the trunk should be named e.g.
BLD39; for a branch, say sandwich, they
should be named e.g. sandwich-BLD7.
Builds should be named according to the product they represent (for
open source builds, NetBeansIDE or NetBeansPlatform);
then the code branch they are built from (for example, release35,
or simply dev for trunk development builds); and then a build
number. For example, NetBeansIDE-dev-200311251900.zip or
NetBeansPlatform-dev-200311251900.zip.
Modules are given a short and punctuation-free name for use in CVS,
build scripts, etc. For example, jarpackager or image.
Directory Structure
The NetBeans CVS repository is organized by "modules", which in
most cases means an actual IDE module, but can also mean special
distinguished parts of the source base such as the Open APIs. Refer to
the
modules list for a complete list of
these modules.
Within a module, there can be various files and subdirectories.
There are certain special naming conventions used mainly to increase
clarity and familiarity of the source organization.
A module may have any of the following subcomponents:
-
src/ - the Java source code for a module. This is
arranged in a package hierarchy. For example, the Form Editor module
contains a source file in the path
form/src/org/netbeans/modules/form/FormEditorModule.java.
-
manifest.mf - the JAR manifest for the module. In
the case of real IDE modules using the Open APIs, this manifest
contains special attributes informing the IDE of what the module
contains, as well as metainformation such as name and version.
-
libsrc/ - source code for any libraries associated
with the module. Some "modules" are just a library. Again this is a
package hierarchy. For example, the Editor module includes source code
for the NetBeans-specific portions under src/, but
general code to implement a Swing EditorKit is under this
directory - for example,
editor/libsrc/org/netbeans/editor/BaseKit.java.
-
javahelp/ - JavaHelp files and HTML for online
documentation for the module, as specified in the Open APIs. In a
package hierarchy. This may be placed inside the module JAR, or in the
docs/ directory in an IDE installation. For example,
crosscompile/javahelp/org/netbeans/modules/crosscompile/CCHelpSet.hs.
-
build.xml - Ant-based build script
for the module.
-
test/ - test suites, probably using
XTest.
-
release/ - files to be placed in the IDE's
installation directory, rather than in the module JAR itself.
Subdirectories should match the installation structure. For example,
form/release/beans/TimerBean.jar.
Only used for CDDL-covered files.
external/ - third-party files not covered by the
Common Development and Distribution License.
-
www/ - HTML web content for the module's associated
minisite. For example, form/www/index.html is
the index page.
-
www/plans/ - planned and implemented features for the module
as described in the Feature
List document.
apichanges.xml - list of API changes made to the module,
in a standardized XML format
-
src/.../package.html and src/.../doc-files/*.html - documentation for the API.
arch.xml - architectural descriptions of a module in a standardized
XML questionnaire format
More standard names can of course be added if there is a conventional
use for them.
Virtual Modules
CVS also permits us to provide "virtual" modules which are built of
pieces of physical modules. For example, some developers will want
access to all source code at once, without having to check out
different top-level modules, find the
src/
subdirectories, and deal with them separately. So you can instead
check out
nbsrc as
a module, and get the source code from the core and all stable modules
and libraries together in one package hierarchy - for example, you
would get
nbsrc/org/openide/actions/PrintAction.java
from the physical location
openide/src/org/openide/actions/PrintAction.java.
However you cannot build the IDE from such a checkout,
you need the straight repository structure of sources for that. Such
aliases are only good for looking at sources, not using them.
It is
easy for the CVS administrator to create and modify virtual module mappings. Once you have one
checked out, you can use contained sources from CVS just like plain
modules - diff them, update them, check in, etc. (Just don't use cvs update -d
on directories with nonstandard structure because CVS will get confused.)
netbeans's CVS repository has a number of existing virtual
module definitions. Major ones include:
| Module name | Directory created | Contents | Safe for cvs up -d |
all | many directories:
core, openide, ... | everything in
the repository | yes |
standard | as above | everything
in the repository needed to create a build with the standard module
configuration used in releases | yes |
core, java, ... | (same as
module name) | just that one component, but everything in
it | yes |
nbsrc | nbsrc | all
source code (but not manifests, JavaHelp documentation, etc.) |
no |
src_exper | nbsrc |
experimental module source | no |
src_basic_modules |
nbsrc | stable module source | no |
src_core | nbsrc |
IDE core source code | no |
src_basic | nbsrc |
all stable source, modules and core and libraries | no |
src_editor, src_openfile, ... |
nbsrc | source for a module, section of a
module, library, etc. | no |
nbmanifests |
nbmanifests | all module manifests | no |
mani_java, mani_projects, ... |
nbmanifests | manifest for the given
module | no |
nbdocs | nbdocs | all
IDE documentation | no |
For a current list of available modules, use
cvs checkout -c. The IDE's mount configuration
dialog also lets you pick one from a list box.
