============================================================================== Dos Navigator Open Source Project Based on Dos Navigator (C) 1991-1999 RIT Research Labs ============================================================================== Last revision date: Wednesday November 28 2001 Table of Contents 1. General issues 2. Creating patches 3. Programming style 4. Applying patches 5. [CHANGED] New DN versions distribution 6. [CHANGED] Project coordinators 1. General issues Dos Navigator Open Source Project is dedicated for development of the popular file shell Dos Navigator (DN) through collective efforts of an open group of programmers. Programmers participating in the project do not carry out material profit, but everyone is mentioned in the authors list of every consequential version. The project participants should be aware that the source text they create will be distributed publicly and is subject for free usage and modification while preserving the author's copyrights. Third party companies and programmer groups can create products derived from Dos Navigator Open Source while maintaining the following conditions: 1. Keeping all the project participants' and coordinators' names in the About box and authors.txt file included with all new versions 2. Keeping dnosp.txt and authors.txt files in the distribution package 3. Including in the About box and in the text documentation the line "Based on Dos Navigator Open Source" Not meeting these conditions is considered a violation of project participants' copyrights. The collective of programmers is open, and no kind of registration is required to enter or exit the project. The project coordinator accumulates the changes made by the project participants, compiles new versions of DN, tests the new features for collective functioning and periodically releases new versions. All the changes the project participants make they send to the coordinator on the source text level. The means of communication to the coordinator are listed at the bottom of this document. The coordinator is elected. In case of impossibility or the lack of desire from the effective coordinator to continue his job, expressed either in a public message or in failing to communicate to project participants for more than a month, failing to release new DN version for more than a month, or failing to communicate for more than two weeks without an explicit temporary transfer of the coordinatorship to another project participant, or also in case if most of the project participants publicly express that they are unsatisfied by the coordinator's work since he or she was last elected, the coordinator is re-elected. Anybody who publicly expresses so can participate as a candidate, and the coordinator is elected by a simple majority of votes by the RU.SHELL.DN subscribers. The discussion of project details and the collaborative communication between the programmers that is of interest to a significant number of subscribers is carried out in the RU.SHELL.DN Fidonet echo area. This document is posted to RU.SHELL.DN every month or immediately when it is modified. The modifications are marked with [NEW] and [CHANGED] in the table of contents. Those who have the technical ability are recommended to post copies of this document to the appropriate Fidonet areas (shells, programming) as well as to other computer networks. Localization is welcome. Localization for a national language can be done by creating a new set of language resources (and not by derival of a separate DN version). If you have decided to start DN localization for a specific language, please communicate to the coordinator (see bottom of this document for coordinates). Translation of this document to other languages is welcome. 2. Creating patches The preferred form of submitting source code modifications is a patch. The patch method is widely utilized in a number of large projects. For an example see the Linux operating system kernel, whose source text is available at ftp://www.kernel.ru.org/pub/Linux/kernel/. A patch is the text resulting from the comparison of two text files or directories with files. Patches are saved in such form that permits applying a patch to one of those files (or directories) making it same with the other. In our project a patch is a result of comparison between two DN source code directories, first being the current (base) version of DN and the second being the same version with some kind of modification made. The diff utility is used to create patches. It was ported from UNIX and, as available now, works in Win32 console mode and in 32-bit DOS protected mode - DPMI (DOS/4GW). Please make sure that you have the diff port version PORT.2 or higher, since the previous port could behave incorrectly. Full description of diff as well as its source code is available from the project coordinator. To compare two directories, the following command should be used: diff -urN base_version_dir modified_version_dir >file.patch It is considered that two subdirectories of the current directory are compared. The description of the -u, -r and -N options (which can be combined in a single option) can be found in the built-in help text: diff --help |more All the options are case sensitive (this is the UNIX standard). It is recommended to name patch files as shown: dn-base_version-application_subject.patch For example: dn-1-51-phonebook-export.patch Modification can span multiple files, include new (added) files and text files other than pas files (resource definition files, etc). It is not recommended to combine in one patch different modifications that are not related to each other. Please note the patch description template, which is recommended to be used to write patch description files. The name format recommended for these files is: dn-base_version-application_subject.info Please refrain from using space characters as well as more than one dot character in the names of patch file itself and its description file, as these can cause problems under certain operating systems. Both files should be packed together with an archiver supporting long file names (WinZip is recommended - http://www.winzip.com/), and the archive should be given a short name to avoid various mailing problems. Such archives are rather compact, making it possible to send them UU-encoded in netmail messages. It is recommended to start names for this archives with the last two digits of the base version number. For example, 01dsvcen.zip is a reasonable name for an archive containing a patch based on DN 1.51.01 sources. Those project participants who do not have the technical ability to create archives in accordance to the recommendations stated above can create archives in the way they find it possible and convenient, but in this case the archives should be sent to the coordinator as private mail. 3. Programming style Due to a rather large number of programmers participating in the project, it is desirable to follow the recommendations stated below to make collaboration easier. The project is international at the present time, so all comments in the source text should be written in English. When a modification of language resources is necessary, change resources only for the language you know, and include a note in the patch description file stating for what languages the modification was made. The coordinator will make the modifications for the other languages himself or by communicating to the native speakers of those languages. All the messages, text, dialogs and other elements of the user interface should be localizable. This means that these items should be based on the language resource contents. An exclusion can be made only for a special kind of fatal error messages and some other occasions when it is technically impossible to access the language resources. If several lines are changed or added, these lines should be marked with a comment with the programmer's name or nickname, for example, { X-Man }. When a large group of lines is added (like a whole function), its top and bottom should be marked with such comments, each spanning a whole separate line. When adding a constant to a group of numeric constants (like cmXXXX), the first unoccupied value is recommended to be used for the new constant rather than shifting values for a range of other constants. If a feature is introduced in a patch, and this feature is rather standalone in the sense that it can be easily removed without impairing other functionality, this feature should be made optional at compile time by surrounding the new code with conditional compilation directives and including a conditional define directive for the new feature in stdefine.inc file. When adding features that are based on some DOS virtual machine features or services under a particular operating system, a service availability check or an operating system check should be performed before actually...
marcinvx