DOS Navigator Open Source Project

Based on Dos Navigator (C) 1991-1999 RIT Research Labs


Last revision date: Tuesday February 20 2001

Table of Contents

  1. General issues
  2. Creating patches
  3. Programming style
  4. Applying patches
  5. New DN versions distribution
  6. 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 programers.

Programmers participating in the project do not carry out material profit, but everyone is metnioned 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 apropriate 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.

top^

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.

top^

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 sence 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 using such services or features. For the operating system check the opSys variable should be analyzed. The opSys variable is defined in the Advance unit along with a set of numeric constants representing different operating systems. Values of the constants can be bitwisely combined, meaning that the environment provides functionality of more than one operating system (possible under some emulators). Feel free to add new constants to that set and apropriately expanding the functionality of the CheckOS procedure.

Please do not include history.txt, authors.txt and the About box updates in your patches. These changes are made by the project coordinator.

top^

4. Applying patches

The patch utility is complementary to diff and is used to apply patches.

To apply a patch, the following command should be used:

patch -p1 < file.patch

(Assuming you have the ported patch tool version PORT.2 or higher.)

It is considered that the current directory is the directory with the current DN version (the directory name is not significant).

The vesion of source code subject to patch application does not have to be identical to the base version. Practically this means that the patch utility has some amount of tolerance to the source code changes and different patches can be applied to the same sources independently. But since accumulation of sources text changes can lead to exhausting the patch utility tolerance, all patches should be created basing on the latest source version available.

The patch utility automatically detects the situation when the patch being applied has already been applied to the source code. In this case, the utility works in reversed mode, removing the patch without affecting the others.

top^

5. New DN versions distribution

New DN versions are distributed by the project coordinator. The NAVIGATOR fileecho serves for this purpose. The new versions are also available at the following Internet addresses:

Each new version is released as four packages:

The fourth packet contains screensavers, xlat tables, Windows icons and examples of text configuration files. This package is not released with every version but only when an update is necessary.

All four packets include the authors list (authors.txt) and the revision history (history.txt) as well as this document (dnosp.txt). The source code package also has the patch description template (template.txt) inside. The revision history for the period of RIT Labs developing and support of DN along with the RIT Labs copyright information is placed in a separate file (ritlabs.txt).

When needed, other packages may be released as well, such as localization sets for national languages.

With each new version, two more files are released:

Beta versions may be released when necessary. A beta version is a supple-mentary release intended solely for beta-testing pruposes, not for general usage. A person who is going to do beta-testing is encouraged to mail the project coordinator and give information about which version would be tested, and in what hardware and software environment (regardless of whether he or she did beta-testing of prior versions).

While in beta-state, new beta-versions are released each time when two weeks elapse since the last beta-version was released and not less than twenty new patches were installed, or when four weeks elapse.

top^

6. Project coordinators

First coordinator:
Max Vasilyev
2:5057/33.36@fidonet
piwamoto@pisem.net
http://www.sama.ru/~piwamoto/

Second coordinator:
Eugeny Zvyagintzev
2:5004/18.60@fidonet
john@omsktyre.com

top^