# Introduction

This document lists changes made to the Diff APIs. Please ask on the `nbdev@netbeans.org` mailing list if you have any questions about the details of a change, or are wondering how to convert existing code to be compatible.

In general the NetBeans core API team has several responsibilities:

1. Avoid incompatible changes to the APIs whenever possible. This refers to both literal incompatibilities to the signatures of accessible API classes (including both source compatibility and binary compatibility, which sometimes differ); and semantic incompatibilities, for example changes in threading behavior of a method call.
2. Document all API changes, incompatible or compatible, in this document, with proper explanation of the change and timestamp, and document the changes at the same time the actual change is made.
3. Maintain API documentation so that it is up-to-date with respect to the actual APIs, both in prose documentation and Javadoc. When an API feature is ambiguously described, clarify the documentation to state precisely what it is expected to do; it is acceptable to specify that some aspect of its behavior is undefined, provided this is explicitly documented. If a feature is publicly accessible only for unavoidable technical reasons, document that this is so, and who is permitted to actually make use of it.
4. Annotate new APIs with their time of addition: in Javadoc using the `@since` tag, or as appropriate in prose. The annotation should include both the date, and the current OpenIDE specification version, to make it easy for module authors to depend on the new API.
5. Announce API changes on the mailing list; incompatible changes must be announced in advance to give any users of the old API a chance to veto the change.
6. Be prepared to publicly explain the meaning and intended use of an API feature, and defend changes to it if requested.
7. Assist anyone posting to the mailing list in fixing their code to be compatible with a change, if this is necessary and desired.
8. Provide a workaround to restore compatibility for a previously incompatible API change, if this is requested on the mailing list and deemed feasible.
9. Minimize the size of the APIs by rejecting compatible changes which substantially increase complexity and are not strictly needed.
10. Attempt to maintain an API design which permits interesting and useful changes to be compatible.
11. Attempt to cluster incompatible changes into infrequent batches of changes, specified and discussed well in advance, to be applied when making a new major release of the IDE. This should be done to remove previously deprecated features with a longstanding better alternative, and otherwise to enhance the clarity, consistency, and flexibility of the APIs.
12. Make changes only on the trunk, not stabilization branches. When an API change is required in a stabilization branch to support an important bug fix, explicitly mention that in this document. (Bug fixes to API-related code not affecting its signature or documented semantics may be made at any time.)
13. Increase the OpenIDE specification version listed in the core whenever a compatible API change is made, if some module is also being changed to take advantage of a newer API. The module should then list a dependency on the newer specification version in its manifest, to ensure that the newer version of the module is not accidentally run on an API-older core. Confirm that the specification version is also bumped up both before and after a branch is made which affects the APIs, to ensure that API changes can be cleanly ordered relative to branch points.

## What do the Dates Mean?

The supplied dates indicate when the API change was made, on the CVS trunk. From this you can generally tell whether the change should be present in a given build or not; for trunk builds, simply whether it was made before or after the change; for builds on a stabilization branch, whether the branch was made before or after the given date. In some cases corresponding API changes have been made both in the trunk and in an in-progress stabilization branch, if they were needed for a bug fix; this ought to be marked in this list.

- The `release33` branch was made on Nov 23 '01 for use in the NetBeans 3.3.1 release, and later for development of Forte for Java (codename Orion).
- The `release330` branch was made on Nov 23 '01 for use in the NetBeans 3.3 release.
- The `release32` branch was made on Mar 10 '01 for use in the NetBeans 3.2 release, and later for NetBeans 3.2.1 and Forte for Java 3.0.
- The `release31` branch was made on Nov 7 '00 for use in the NetBeans 3.1 release.
- The `boston` branch was made on Jun 29 '00 and used for betas and the FCS of Forte for Java 2.0. A number of API changes made after this date have in fact been incorporated into the branch.
- All changes listed here were made after the `postfcs` branch, which produced the Forte for Java 8xx series builds (1.0.x FCS and betas) and also the NetBeans 3.0 release. So they do not apply to these builds; this version of the change list was started immediately after this branch was made (early Feb '00).

# Index of APIs

- Diff API
- Merge API

# Incompatible changes by date

Fuller descriptions of all changes can be found below (follow links).

Not all deprecations are listed here, assuming that the deprecated APIs continue to essentially work. For a full deprecation list, please consult the Javadoc.

# All changes by date

- (May 23 '05) DiffView interface added
- (Apr 24 '02) StreamSource class added
- (Apr 24 '02) MergeVisualizer class added
- (Feb 18 '02) The Diff APIs created

# Changes by version

These API specification versions may be used to indicate that a module requires a certain API feature in order to function. For example, if you see here a feature you need which is labelled `1.20`, your manifest should contain in its main attributes the line:

    OpenIDE-Module-Module-Dependencies: org.netbeans.modules.diff/1 > 1.20

- (1.13) DiffView interface added
- (1.5) MergeVisualizer class added
- (1.4) StreamSource class added
- (1.3) The Diff APIs created

# Changes by affected class

# Details of all changes by API and date

## Diff API

### DiffView interface added

May 23 '05; API spec. version: 1.13; made by: mentlicher
A controler interface, that allows to programmatically control the diff component.

### StreamSource class added

Apr 24 '02; API spec. version: 1.4; made by: mentlicher
Class, that is used as a source of named streams for diff and merge stuff.

### The Diff APIs created

Feb 18 '02; API spec. version: 1.3; made by: mentlicher
The base classes adedd.

## Merge API

### MergeVisualizer class added

Apr 24 '02; API spec. version: 1.5; made by: mentlicher
Service, that is used to resolve merge collisions.