How to Contribute to the Globus Toolkit®
The Globus Toolkit is an open source development effort. We encourage others to participate in the development of this important body of Grid software.
- General Principles
- Initiating the Contribution Process
- Coding Guidelines
- Expectations for Testing
- Expectations for Documentation
- Coordination of Releases
- Expectations for Support
The goal of these guidelines is to provide mechanisms that enable and encourage people to contribute useful and appropriate Grid technologies to the Globus Toolkit. By defining well-understood mechanisms and soliciting feedback on these mechanisms from the community, we hope to ensure that there are benefits both to the contributors and to the Grid community as a whole for including new software components in the Globus Toolkit.
The Globus Toolkit is used by hundreds of projects and thousands of people worldwide. Our (collective) ability to support this software is very important. The standards and expectations presented here for software testing, documentation, coding standards, and technical support are intended to ensure that the Globus Toolkit is usable and supportable for this broadening user community. As this community expands, user expectations become higher and it becomes even more important to ensure that we continue to meet reasonable expectations for the software's quality and reliability.
Because the Grid community is expanding and now includes for-profit and non-profit enterprises, educational institutions and government organizations, broad open source licensing is critical. The licensing requirements described here are vital to the continued acceptance of the Globus Toolkit as a reference implementation for Grid standards.
A step-by-step document on the way to initiate the process for contributions can be found here.
No one, least of all ourselves, wants to be bothered with legal issues, particularly not for open source software! On the other hand, our ability to distribute the Globus Toolkit software freely and others' ability to use the software without restriction both require that we address some legal concerns.
The central issue is that we must establish clearly our right to distribute all contributions, so that neither we nor our users are at risk for subsequent legal action. This means that we require contributors to establish our legal right to distribute the software without constraint by signing one or both of the following license agreements.
- Globus Toolkit Individual Contributor's License Agreement - Required for everyone who obtains committer rights.
- Globus Toolkit Corporate Contributor's License Agreement - Required for all companies with employees who have signed the individual agreement (not required for self-employed individuals who have already signed the individual agreement).
Co-branding is an important element in making a software contribution to the Globus Toolkit. Co-branding makes it possible for users of Globus Toolkit components to recognize both that the software is part of the Globus Toolkit and that it has been contributed by a specific source, whether that source is the Globus Alliance or some other group or individual.
Globus Toolkit users want to see some visible link between the components of the Globus Toolkit. If a component or its documentation bears no resemblance to the rest of the Toolkit, the user may doubt whether it meets the same standards as the rest of the Toolkit or will work well with the rest of the Toolkit. The Globus Toolkit "brand" implies certain fundamental characteristics about a piece of software: a well-understood style for support, documentation, testing, code quality, etc. It would not make sense to contribute a piece of software to the Globus Toolkit unless it was desirable to give people the sense that the Globus Toolkit brand applies to the software.
Contributors may also be interested in having users recognize the source of their contributed components. Software authors may want credit for their work, flexibility in their presentation style for documentation or other materials, or other benefits that preclude a seamless integration with the Globus Alliance's "look and feel".
The co-branding mechanisms presented here are intended to provide both the benefits of having a contributed component clearly associated with the Globus Toolkit and the benefits of maintaining some distinction between the people who contributed the components and the Globus Alliance.
Credit Given to Contributors
The Globus Toolkit is a community effort and we are committed to recognizing the contributions of the community: in the code itself, in this web site, and elsewhere. In particular, we are committed to ensuring that contributors to the Globus Toolkit are credited publicly for their contributions.
One means of accomplishing this is the list of contributors on the Globus Alliance website. (See our list of contributors. Please let us know if we are missing anyone.)
Another way is by including documentation about the contributed components on the Globus Toolkit website. This documentation may be hosted on our site or hosted on a contributor website, but we will maintain links to this material and give you mechanisms for linking your documentation to the rest of the Globus Toolkit. For this reason, it is important that contributors provide documentation of their contributions (see Expectations for Documentation below) and also use the Globus Toolkit logo and include a statement regarding inclusion in the Globus Toolkit in their documentation as described in the following sections.
Another way that we ensure recognition of contributors is by covering contributed components (with appropriate credits) in our Globus Toolkit tutorials. We regularly present overviews, developer tutorials, and administrator tutorials on the Globus Toolkit to audiences around the world. For this reason, it is important that contributors provide slides that we can use in our tutorials. (See Expectations for Documentation below.) We have already licensed our tutorial presentations for use by others, so you may use our slides in your own presentations however you feel it is appropriate.
Using the Globus Toolkit Logo
When preparing documentation and other materials (web pages, etc.) relating to your contribution, you will find it useful to make a visual link to the Globus Toolkit. This assures readers and users of your software that it is a part of the Globus Toolkit and is intended for use with the other Globus Toolkit components.
The Globus Alliance logo is not appropriate for this purpose, as this logo is only to be used by members of the Globus Alliance. Our trademark protects the Globus Alliance logo from unauthorized use, and we are obligated to protect this trademark in order to maintain its value as a symbol of our group.
The Globus Toolkit logo has been created specifically for use by contributors to the Globus Toolkit to identify their work as a part of the Toolkit. We encourage you to use this logo on your documentation and any other materials describing your contributions once we have agreed to include them in the Globus Toolkit.
Naturally, we expect that you will also use your own logos, trademarks, or other identifying visual information to identify yourself as the originators of the work.
Statement of Inclusion in the Globus Toolkit
We strongly encourage you to include a statement in your documentation that explains that the work has been included in the Globus Toolkit. This will clarify for readers that your software is included in the Globus Toolkit and is intended for use with other Globus Toolkit components. An example of such a statement, which you may feel free to use in your work, is included below.
This software [or: <name of product>] is included in the Globus Toolkit®, distributed by the Globus Alliance at http://www.globus.org/toolkit/. Unlimited use is allowed under the terms of a liberal open source license.
Appropriate use of "Globus Alliance" and "Globus Toolkit"
To avoid confusion among members of our projects and yours and more importantly among the user community, proper use of the terms "Globus Alliance" and "Globus Toolkit" is vital.
As a contributor to the Globus Toolkit, you are encouraged to use the Globus Toolkit logo and to make statements regarding the inclusion of your work in the Globus Toolkit. We will list you as a contributor to the Globus Toolkit.
The Globus Alliance is a specific group of people. Members of the Globus Alliance are listed on our website at http://www.globus.org/alliance/team/. If you are not listed on this page, please do not refer to yourself as a member of the Globus Alliance. We appreciate your sensitivity in this matter.
The Globus Alliance's coding guidelines for both Java and C are documented on the Globus Toolkit website at http://www.globus.org/toolkit/docs/development/coding_guidelines.html.
As a code contributor, you are not required to adhere to these standards. However, there are at least three reasons why you may find it helpful to use these standards as a reference when you develop your code.
The first reason is that most of the code in the Globus Toolkit already follows these standards, and users and developers will find it easier to follow your code, use it, debug it, and support it if you follow similar standards. If your code looks radically different from the other code in the Toolkit, it is more likely that users and other developers will not use it or will leave it to you to handle all of the maintenance and support for the code. If your code looks like the rest of the code in the Toolkit, it is likely that others will feel more comfortable with it and help you to maintain and support it.
The second reason is that the members of the Globus Alliance will be more likely to accept your code as a contribution to the Globus Toolkit if you follow the same standards as we have followed, for essentially the same reasons as those listed above. We will certainly be involved in helping to support and maintain your code once it is part of the Globus Toolkit. This will be easier for us if it follows the same standards as the rest of the code.
The third reason is that these standards are useful ones. The standards used by the Globus Alliance were developed by talented programmers from a broad range of backgrounds. The resulting code has been repeatedly cited as an example of high-quality code by users all over the world—including commercial and other professional software development organizations. These standards have allowed us to support and maintain a large base of code for several years, and new members of our team have found the code easy to learn and easy to adapt to new requirements during this time.
Again, there is no requirement for contributed code to use the standards documented on our website. Following the standards, however, should result in code that is easier for others to use and maintain, more likely to be accepted by the Globus Alliance, and higher- quality in general.
Software in the Globus Toolkit is expected to work on a wide range of platforms and in a wide range of systems. Testing at several stages of the software development and release process is essential to meeting this expectation.
We expect that all discrete software components (libraries, service executables, tool executables) will have unit tests associated with them that ensure their methods and functions work according to some set of specifications (which ideally will be documented). These unit tests should be run on as many platforms as possible before code is contributed to the Globus Toolkit.
Including these unit tests in the contributed software is a wonderful way to help the Globus Alliance ensure that the software works as we integrate it into the Globus Toolkit experimental release. This will make us much more comfortable with the contribution process and possibly speed up release of the contribution. It is also is much appreciated by the Globus Toolkit user community, as it gives others the tools needed to test ports of the software on new platforms and individual builds on any platform. We strongly encourage the inclusion of unit tests in the contributed software.
In addition to units tests, we expect that component-level tests will also be designed, developed, and run prior to contribution to the Globus Toolkit.
For example, if a code contribution includes a library, a client tool built on the library, and a service built on the library, one component-level test might involve setting up the service with a specific configuration and starting state and then running the client tool against the service with specific inputs to ensure that the client tool and the service both exhibit the expected behavior (output data, state changes, log entries, etc.).
Unlike unit tests, component-level tests may not actually involve test code. They can, however, be documented so that others can reproduce them. Ideally, a code contribution would include a description of reasonable tests to verify that the software is working properly once it is built and all unit tests pass.
Documentation is critical for adoption of software by users. Since a typical reason for including software in the Globus Toolkit is to encourage use by others, documentation is particularly important for contributions to the Globus Toolkit.
Specifications for APIs, Protocols, and Services
We strongly encourage contributors to document the APIs provided by their contributions, the protocols used in their implementations, and the services provided (if any). Software included in the Globus Toolkit will be used as building blocks for Grid applications and Grid infrastructures. These uses require well-documented APIs, protocols, and services.
We recommend that each API, protocol, and service be documented separately. (Documents may, of course, reference each other.) Documentation should be web- accessible so that it may be linked to from the Globus Toolkit website and other Grid resources. The Globus Alliance will host your documentation if you do not have access to your own public web server.
The Globus Alliance currently uses the Doxygen system for documenting APIs. Doxygen uses a Javadoc markup format within code comments to tightly integrate code and its documentation, improving the accuracy of the documentation and encouraging updates when code changes. If you also use Doxygen or a Javadoc mechanism, your API specifications can be automatically generated by Globus Toolkit users.
High-level documentation—including user guides, installation guides, system administrator guides, etc.—is also important to users of the Globus Toolkit. These guides make it easier for users to install, configure, maintain, and use your software components.
If your components require special instructions for building the software, we recommend that you provide written instructions for users. If your components include anything other than libraries (command-line tools, graphic user interfaces, services), we recommend that you provide written instructions for the installation and configuration of your software. Members of the Globus Alliance can integrate these instructions in to the Globus Toolkit installation guide, administration guide, and other resources.
Once your contributions are included in the Globus Toolkit, members of the Globus Alliance will want to explain these contributions during our frequent tutorials and presentations. (See "Co-branding" above, specifically "Credit Given to Contributors".) We strongly encourage contributors to provide PowerPoint slides that describe their contributions that can be included in the Globus Toolkit tutorials and other presentations. Slides describing the design of your contributions will be included in overview and developer tutorials. Slides describing APIs, protocols, or services will be included in developer tutorials. Slides describing the installations and/or configuration of your software will be included in administrator tutorials.
It is important that all components in the Globus Toolkit be covered in the Globus Toolkit tutorials. We will certainly provide appropriate acknowledgement to contributors in these presentations.
Work with the Latest Code
When you are developing your code, please be sure to use the latest "experimental" version of the Globus Toolkit. The latest experimental version is the version on which the Globus Alliance developers base their new code, and it is the version that will eventually become the next "stable release" of the Globus Toolkit. The experimental version includes the contents of the latest stable release plus any components that have been released to the public (as beta releases) since then. Using this version during your development helps to ensure that your code will work with the next stable release of the Globus Toolkit.
The latest experimental release of the Globus Toolkit is available via anonymous CVS from the Globus Alliance's CVS repository. Please refer to the information on the Globus Alliance's website regarding remote access to CVS.
The Grid Packaging Technology (GPT) used by the Globus Toolkit allows individual components to be packaged and released separately from the rest of the Globus Toolkit. When you make a contribution to the Globus Toolkit, you will be able to release packages for your components that replace or add to existing Globus Toolkit software. The Globus Alliance periodically prepares releases of the entire Globus Toolkit in order to assign a common version number for use by the community. (E.g., Globus Toolkit 2.0, 2.1, 2.2, etc.) These version numbers can serve as reference points for people in determining the compatibility of their installations or the features supported by their individual installations. It is here that coordination among component contributors is required.
Globus Toolkit Release Strategy
Globus Toolkit releases are provided in pairs. These pairs are always released simultaneously and they are initially identical. The two releases change in different ways over time. Both releases are available via the Globus Alliance anonymous FTP server and linked to from the Globus Toolkit download page.
- A stable release is available for people who want a "stable" release, with bug fixes provided over time.
- An experimental release is available for people who want the latest software, including any beta releases that have been made available since the last stable release.
The stable release is numbered using an even number for the secondary version number. The experimental release is numbered with the next higher odd number. So stable release 2.4, for example, would be accompanied by experimental release 2.5. Again, when these releases are first made available, they are identical.
NOTE: Remote CVS users will always see the experimental release unless they use branches or tags to specify a stable release or a specific release update.
Updates to individual packages within the stable release will be provided whenever bug fixes are made. These updates will be listed on the Globus Toolkit download page (or a linked page).
The stable release will be updated periodically via automated processes, and these updates (2.0.1, 2.0.2, 2.0.3, etc.) will include any bug fixes made since the last stable release update. These updates will not include new features, however. These updates will include all Globus Toolkit source bundles, but most likely will not include binary bundles.
The experimental release will also be updated periodically via automated processes, and these updates (2.1.1, 2.1.2, 2.1.3, etc.) will include bug fixes and new features provided by development efforts that have reached a beta release point. (Beta releases for occur when a development team's work has been finished, all testing is complete, and the code is ready to be made available to the public for general use.)
The stable and experimental releases will remain continue to be updated until it is decided by the Globus Alliance team that there are enough compelling new features in the experimental release that it is time to make a new stable release that contains these features.
When this occurs, a new set of stable/experimental releases will be made available. The contents of both releases will be the same as the previous experimental release, and updates will then proceed as described above.
Alpha releases will be provided to specific audiences by individual development teams. These alpha releases will contain features from a specific development project in progress. Alpha releases will most likely be complete releases of the Globus Toolkit (source bundles, and perhaps binary bundles).
It is not recommended that alpha releases be provided as package updates to a stable or an experimental release. The automated release mechanism will make it very easy to generate a complete release of the Globus Toolkit for alpha users, and doing so will greatly simplify support for the resulting alpha code. Furthermore, package numbers for GPT packages contained in alpha releases will very likely collide with package numbers from other alpha, stable, or experimental releases. For all of these reasons, it is recommended that alpha releases be provided as complete releases and that alpha testers discard these releases after testing is complete.
Where do contributors need to get involved?
Contributors to the Globus Toolkit will need to be involved at several points in the Globus Toolkit release process.
Contributors may offer alpha releases of their work in progress at any time. As described above, these should be complete releases of the Globus Toolkit (based on the latest experimental release, plus the work in progress). Alpha testers should discard their alpha releases when their testing is completed.
Contributors may be called on to fix bugs, packaging, configuration, or installation issues when the Globus Alliance is integrating their code into a new experimental release. Since experimental releases must be working versions of the Globus Toolkit, if any component fails to build, configure, or install correctly, it will interfere with the experimental release. The authors of code with such issues must address these problems promptly.
Contributors may also (less frequently) be called on to assist with the next stable release following their contribution. This is unlikely to happen, since by the time of the stable release, the code will already have appeared in experimental releases and all issues should have already been identified by users of the experimental releases and corrected by the appropriate developers.
User support for the Globus Toolkit is provided by the developers of each component. By contributing code to the Globus Toolkit, you accept responsibility for providing user support, and presumably for fixing bugs in your code that are found by users. The Globus Alliance is not obligated to provide user support for your code or to fix bugs in your code.
Participate in Bugzilla
The Globus Alliance's Bugzilla interface allows new bug reports and questions to be assigned to anyone registered with the Bugzilla system. When you contribute code to the Globus Toolkit, we will begin to assign bugs found in your code or questions about your code to you or members of your team.
You must tell us who we should assign bugs and questions regarding your code to. You will be responsible for ensuring that these people accept bug reports and resolve them by submitting patches, clarifying the code or documentation, or answering questions about the code's specifications.
Please note that the Bugzilla system is public. All bug reports and questions are visible to the public, and our responses to these reports and questions are also public. If it becomes clear that you or your assigned staff are not responding to bug reports or questions relating to your software, this will be quite visible to the user community. In extreme cases, this may result in your code being removed from the Globus Toolkit. The Globus Toolkit's user community is quite large and is increasingly broad. You will find that the Bugzilla system will provide you with considerable feedback regarding your software. If you are responsive to bug reports and questions, you can be assured that the quality of your code and documentation will improve over time as a result of this feedback.