Development Process
From Open Watcom
Summary: This document outlines the development process: intentions, general attributes, and high-level processes. The goal is to ease the collaborative development for all involved parties and to provide basic knowledge for new participants; the document serves as a crude replacement of orally distributed lore common on physically localized development campuses. The recommended procedures here are intended to give all interested parties a chance to participate and contribute at their own level.
Contents |
Fundamentals
This chapter provides an overview of what Open Watcom is, its relationship to the earlier Watcom commercial compiler products, and a description of the principles and procedures to be used by contributors who wish to provide enhancements or bug fixes.
The Open Watcom project
What is it?
Open Watcom is an open source project which is based on nearly complete source code for the commercial Watcom compilers, tools and user documentation. It is a center for a community development effort where contributors can collaborate on improving the software and documentation, and provide or receive support. The software is almost totally self-contained, which means it has no dependencies on 3rd party packages for producing a working toolchain. The toolchain includes compilers, assemblers, runtime libraries, debugger, documentation, and much more, to deliver a complete set of developer tools. Releases include operating system specific include files from other projects, to avoid duplication of efforts. The Open Watcom project is currently stewarded by SciTech Software, Inc. The license is Sybase Open Watcom Public License version 1.0.
What is different from the commercial Watcom compilers?
This project does not provide commercial end-user support. Each bug fixed and each feature added is based on volunteer work. However, while no one has obligation to fix problems or add enhancements, the source is open so that anyone sufficiently motivated may do so. Third-party software (Microsoft, IBM development kits) is not part of the project, although open source replacements are included. The source code for all components of the binary releases is available to users, as well as the source for internal tools used in the production and build process of the compilers and tools. The commercial compiler verification tools and test applications used previously are not available to the open source project; adding tests for the code is a part of the 'invisible' work performed by contributors. Effort is invested in enhancements such as adherence to new standards and bug fixing, and new tools are added. Investments of time is also made in the area of supporting new OS platforms, adding new features to existing platforms, finishing formerly unreleased CPU specific compiler support, adding support for new CPU architectures, and making formerly internal developer tools part of the released packages.
Communication channels for contributors
Primary: news://news.openwatcom.org
Design Principles
The source code which forms the basis of Open Watcom has been developed over many years, by many different people. Not much exists in the original source to determine what design principles have been applied (usually because the principles were never written down), except for the resulting source code itself and what can be understood from it. Based on the existing source and the work of experienced contributors, a set of design principles is derived and created, which should be used as a guide for new efforts, and applied to older non-conforming subprojects when possible. Software is something which evolves and improvements are almost always possible. There are parts of the source which do not conform to the principles outlined here to the extent that they should, which is natural since processes and guidelines were not formalized before. The principles are important to the future usefulness and maintainability of Open Watcom, and contributors are expected to know and apply them while making changes or additions.
Maintainability
The source code must be formatted according to the Style Guide for the language in question (C or C++). The project's build system must be written (or updated) to cater for inclusion of the new or modified functionality. The documentation must be updated to reflect changes. Setup procedures must be modified (when necessary) to include the new functionality in binary distributions.
Reliability
Whether run on an old DOS box or the newest and coolest workstation, the tools must be reliable above all else. It means that all Open Watcom modules must perform correctly, and provide accurate results. In the event of a failure to perform correctly, proper error messages and/or other diagnostics must be provided. No serious software development can be performed with unstable tools. For contributors this means serious testing before submitting new functionality. Code checked into the repository is required to compile without errors for all supported platforms. Code for automatic regression tests for the features should be provided whenever possible. While contributors aren't expected to test whether modified code correctly runs on every supported platform, they are expected to take the multi-platform nature of Open Watcom into account during design and development.
Compatibility
In every module, compatibility over time must be considered a goal. Breaking binary compatibility with libraries from release to release is out of the question and such changes should only be made after an extensive discussion with the other contributors. Modifying the existing functionality of a command line option is a serious change as well, since it could break existing builds or other supporting components. Whenever a change is potentially breaking backward compatibility, make sure it is absolutely necessary and can not be solved any other way. Make sure the other developers agree with the analysis of the case. If accepted, such change must be properly documented and listed in the release notes to alert users of the incompatibility.
Platform Neutrality
Open Watcom is built from a single source base and in almost all cases, capabilities and feature are equivalent across all platforms. It must continue to be platform neutral to enable easy ports in the future. Make sure platform neutrality is observed in all source added to the project.
Process Principles
Contributing to Open Watcom is more than just understanding the design principles and adding the source code. There are also development processes in place to steer, encourage and ultimately enforce future development to adhere to the stated design principles. These development processes must be understood by contributors to the project.
Open
Open Watcom can clearly benefit from having many contributors using, learning and eventually having the opportunity to change it. Therefore it must be developed out in the open using processes that are transparent and which allow participation at all levels -- some tasks require expert knowledge and skills, but many do not.
Shrink To Fit
Each step of the development process has an important role to play, but certain steps may not be applicable for certain types of proposed changes or the scope of a step may be excessive. Processes must be designed in such a way that the time and materials required to complete a step can be reduced, optimized or even eliminated when the full step is not required, as long as the quality of the tools is not compromised.
Fair
The development process must be structured such that it can be administered in the same way for all contributors. Variations on the scope of a particular step in the process and what is being asked of a contributor must be based not on the contributor but on what is being contributed.
Policies
These policies each distill the positions of many stakeholders into a minimal requirement for project teams and consolidations in each of the technical areas.
Architecture Neutral
All generic (high level language) code shall be tested and run on all supported target platforms. There must be a commitment to keep the code functional.
Bugs
Contributors are expected to resolve all bugs in new features prior to the next release version. Failure to do so can result in the new features not being included. Long standing failure to fix bugs will result in the submitted features being rejected from the source tree.
Licensing of contributions
All contributed software must be freely modifiable and redistributable, licensed under the Sybase Open Watcom Public License version 1.0 or a license that is compatible with it.
Release Management
Release dates and features included will be coordinated between the contributor community and the representative of the current project steward. If general consensus is not reached, the representative of the project steward have the final decision.
Processes
Reporting a bug
- Make sure you are testing the latest version of the tools. No one is likely to fix a bug in old versions of the project.
- Search the [Bugzilla database] to make sure that the bug has not already been reported. If it has been reported, check the problem description to see if you can add relevant information.
- Reduce the material and steps to reproduce the bug to the smallest possible testcase. If it is a compiler problem, make a version of the problematic source as small as possible for inclusion in the bug report -- nearly every bug can be reproduced in less than ten lines of code. Keep in mind that the shorter the testcase is, the more likely it is that the report will be investigated by others.
- If other materials are needed to reproduce a problem (such as binary files), attach them to the bug report.
- Provide a sequence of steps required to reproduce the problem.
- Make sure you include information about host and target platform (operating system) you are running on, and about the environment if there is something unusual about it.
- If possible, make someone you know try to reproduce the bug according to the bug report you made without any help from you. If not, try to do it yourself.
- Make a posting in the contributors group on the news server, stating the bug number and what the perceived problem is, in just a few lines. This is to make more contributors aware of the new problem report.
Note: Much inspiration for and structure of this document came from the “OpenSolaris Development Process”
