Difference between revisions of "Graphical Modeling Framework/Development Guidelines"

Revision as of 11:28, 8 August 2006

General Information

The bullets below should cover all the tasks one would need to accomplish to become a "plugged-in" member of the GMF development community.

Mailing Lists

GMF has two mailing lists, currently. The main developer mailing list [gmf-dev@eclipse.org gmf-dev@eclipse.org] and the release engineering mailing list [gmf-releng@eclipse.org gmf-releng@eclipse.org]. You are welcome to sign up for both, but it is generally sufficient to just be signed up for the developer mailing list. Now, remember that general questions should be posted to the newsgroup and not to the development mailing list! Development topics, architectural discussions, contribution and Committer voting, etc. all take place on the developer mailing list.

To register for the mailing list, you must provide a valid email address and other information here. Note that in order to access the mailing list archive, you need to have a newsgroup user name and password. Information on the newsgroup is below.

Newsgroup

As mentioned above, the newsgroup is where general questions are asked and you are encouraged to ask and answer questions as you wish. Look here for information on how to get a password, in addition to a complete list of Eclipse newsgroups.

Bugzilla

You will most definitely need a Bugzilla account. Look here for information on setting up an account, using Bugzilla, etc. If you're interested in contributing right away, perhaps you can find something here to work on.

Workspace

You will generally work with three (or more) workspaces. Each is discussed here, along with some overall workspace configuration and tips.

Development Instance

In general, you can install whatever you want in your development instance, while most seem to prefer the bare essentials. As long as you have a target instance that is configured properly for GMF development, it doesn't really matter much. You will likely just need to adhere to equal or greater version numbers of both the Eclipse SDK and EMF.

You may elect to configure your development instance to align with the requirements for GMF development and not bother with two... it's up to you. Of course, as we develop against moving targets (Platform, EMF, and GEF milestone releases), using this feature of the PDE is quite useful.

Once your development instance is configured, you'll need to obtain the GMF source code in your workspace. To do this, there are several options, including the CVS Repository Exploring Perspective, a Team Project Set file (one is maintained here), and use the releng tool found here. Each of these is detailed below:

• CVS Repository Exploring Perspective

In the CVS Repositories view, right click and select New > Repository Location... and fill in according to the dialog shown.

Note that a Committer will select 'extssh' for the connection type, and use their supplied user name and password. Find your way to /org.eclipse.gmf/plugins and expand it. Although you're able to check out features, examples, tests, etc., for now, just multi select the plug-ins and right-click. Select 'Check out' and sit back. If all goes well, all the plug-ins will be downloaded and built in your workspace.

• Team Project Set

You can find a gmf.psf file here for use in quickly setting up a workspace with the GMF projects fetched from CVS that you'll need to get started. From File > Import/Export... simply select 'Team Project Set' from the Import list, navigate to the file, and you're done! Another psf file that contains all of GMF is found here.

• Release Engineering Tool

A nice feature of this little-known tool is its ability to synchronize your workspace to the set of projects found in a map file. Of course, you'll first need to obtain the map file, which for GMF is found in the project org.eclipse.gmf/releng/org.eclipse.gmf.releng which you'll need to obtain from CVS. An alternative is to grab the directory.txt file found on most project download sites, add it to a project in your workspace with a .map extension and right-click to Team > Load Map Projects.

Target Instance

The easiest way to find the current requirements for developing GMF is to look at the development update site. The build machine uses a local mirror to install and configure GMF dependencies (and GMF itself, when executing unit tests), so the list here is what is required. Now, try not to use this mirror as your source of obtaining GMF builds and its dependencies.

Now, in order to point your development instance at your target instance that has all the required dependencies for GMF development installed, go to Window > Preferences... > Plug-in Development > Target Platform and point it at the 'eclipse' folder of your target instance.

Runtime Instance

There are several possible scenarios for working with GMF as a developer. What you focus on will impact how you configure your development workspace and runtime instances. Below is a detailed scenario that represents a possible style of work which will be abbreviated here next. If you get it by reading the abbreviated form, great! If not, hopefully you will after reading the longer version and trying it out yourself.

In brief, you will configure a launch configuration to contain the GMF plug-ins and create a project to work with your diagram/domain/mapping models. Once you're done and have generated your runtime plug-ins, return to your development instance and import those project. Then, create a new runtime launch configuration to test the generated diagram plug-ins, deploying only those and the required runtime plug-ins (no need to have all of the SDK present in this second configuration). Got it?

CVS

Currently, all Eclipse projects utilize CVS for their source repository. There is an excellent CVS plug-in provided with the Platform SDK that has been enhanced to work with the automated build process using this tool. This section focuses on some common CVS use cases and this tool's usage in GMF to facilitate our release engineering.

Repository Structure

The structure of GMF's repository is shown below, and is also described in this document. A general document on using CVS with Eclipse projects is maintained here. In short, you'll likely be primarily interested in the plugins directory although anyone using anonymous pserver access can read from all of the modules. Committers using extssh can write to every module. GMF does not (yet) have fine-grained access control over its modules.

/cvsroot/technology CVSROOT (dev.eclipse.org)

/org.eclipse.gmf Graphical Modeling Framework subproject

/contributions GMF code contributions

/doc Project documentation

/examples GMF examples

/features GMF features

/plugins GMF plugins

/releng Build procedure scripts, update site, etc.

/tests GMF unit tests

Creating a Patch

It's likely the second thing you'll do with CVS is create a patch (the first was to obtain the GMF sources). To do this is quite straightforward:

• When you have made the changes or additions to a plug-in, simply right-click the project (or resource) and select Team > Create Patch...
• In the wizard, select the option to "Save in the file system" and create a patch file named after the plug-in.txt (e.g. org.eclipse.gmf.codegen.txt). Note: the naming convention is important to the IP tracking scripts in use by the project, as is the importance of not zipping your patch files, as the size of the file is used to indicate the size of the contribution.
• Submit the patch through Bugzilla. Don't send it directly to a Committer, or to the mailing list, or to the newsgroup. As described in another section of this document, Bugzilla is the best means by which to submit a contribution.

Releng Tool

A tool provided by the Platform team to facilitate release engineering is found here. A list of basic functions for this tool is maintained on the download site, as seen at the bottom of this page for the 3.2 release. A copy of those functions is pasted below:

1. Release to the Team menu. This action will Tag selected projects with the specified version and update the appropriate loaded *.map files with the version. The user must have the *.map files loaded in their workspace and the use must commit the map file changes to the repository when done.

2. Load Map Projects to the Team menu. Select one or more *.map file and this action will load the projects listed in the *.map file into your workspace. Naturally the versions specified in the *.map file will be loaded.

3. Tag Map Projects to the Team menu. Select one or more *Map files and this action will tag the projects listed in the *Map files with a tag you specify.

4. Compare with Released to the Compare menu. Compare the selected projects with the versions referenced in the currently loaded map files.

5. Replace with Released to the Replace menu. Replace the selected projects with the versions referenced in the currently loaded map files.

6. Fix Copyright to the Resource Perspective Projects context menu. Select one or more projects in the Resource Perspective. This action will sanity check the copyright notices in all the *.java and *.properties files. Copyrights will be updated automatically where the tool deems appropriate. A copyright.log file will be written to the workspace directory noting odd conflicts that need to be looked at. You need to commit the changes yourself. This is the tool that was used to do the 2.1 Copyright pass.

Coding

The items here relate to coding standards, best practices and style concerns to maintain GMF code to the high standards expected from an Eclipse project.

Copyright

In accordance with EPL projects, as described here, all source files need to have the appropriate copyright notice. To set this, navigate to Preferences... > Java > Code Style > Code Templates, use the following:

Testing

Bugzilla