~vbursian/research-assistant/intervers

/*! @file RA.documentation.src.h   В этом файле находится исходный текст

                                   для генерации документации к исходным

                                   текстам программы Research Assistant.

*/

 

//******************************************************************************

//******************************************************************************

/*! @mainpage Research Assistant Program

 

*/

 

//******************************************************************************

//******************************************************************************

/*! @page program_structure Program structure

 

 

 

 

*/

 

//******************************************************************************

//******************************************************************************

/*! @page versions Versions

 

 

 

 

*/

 

//******************************************************************************

//******************************************************************************

/*! @page subversions   Subversions and development discipline

 

 

 

 

Нам пора сливаться.  И наводить более строгую дисциплину контроля версий.  Предложения принимаются, индивидуальные вкусы могут быть учтены.  Можно допустить и индивидуальные дисциплины, если они эффективны и понятны другим.  Пока я навязываю свои правила и хочу три вещи:

 

1.  Получить свежие версии ваших собственных текстов и ваши версии текстов, которые вы изменили (Install.cpp, файлы проектов,...).

 

Хотелось бы, чтобы они компилировались, по крайней мере, у вас.

 

Хотелось бы, получить их в виде zip с именем вида

    "RA 101129 DN2VB.zip",

т.е. содержащим дату и от кого кому.

 

ВНИМАНИЕ: наличие суффикса "2VB" означает, что архив неполный, и остальные файлы адресат может найти у себя или скомпилировать самостоятельно.

 

2.  Заведите у себя манеру периодически архивировать все исходники ЦЕЛИКОМ (мои и ваши).  И все эти архивы хранить на флешке.  Все!  За всю историю!  Когда флешка переполнится, сбрасывать на CD.

 

Как правило не стоит включать в архив то, что можно скомпилировать или сгенерить (exe, dll, генерируемые файлы документации,...).  Без них архив RA около 1Mb, а со всем "мусором" больше 20Mb!  Т.е. чистить! Либо до архивации (я использую скрипт или bat-файл), либо уже из архива удалять ненужное.

 

В имя архива обязательно включать дату.  Если в тот же день делается несколько архивов, то можно добавить буквочки "a", "b",...  Полезно ещё добавить имя компа: "RA 101129а blin.zip" (blin -- это не ругательство, а кличка моего ноутбука).  Можно ещё какие-то ремарки приписать сзади.  Я, например, добавляю "-", если версия не компилируется, "!" - для финальных отлаженных версий после значительного развития/переделки, а иногда и слово или фразу, которые напомнят мне, что в этой версии нового.

 

Обычно полные архивы не пересылаются со-программерам, но иногда может потребоваться.  Если архив предназначен для пересылки, то обязательно включить в его имя свои инициалы, чтобы он случайно не потёр архив с той же датой у адресата.

 

Надо бы ещё вести history.log, но лично я пока ленюсь.  После начала официальных релизов это вероятно придётся делать.  Можете показать мне пример прямо сейчас ;-)

 

Примечание: Использование номеров версий имеет смысл только для официальных релизов.  Т.е. после

a) слияния (обязательно!),

b) тестирования (желательно),

c) формирования дистрибутива (желательно, на Read-only CD),

d) и (!!!) смены номера версии для дальнейшей разработки,

   причём согласованно у всех разработчиков.

 

3.  Нужна некая унификация относительной структуры папок, прямо или косвенно касающихся разработки RA.  У меня имеется папка .

 

*/

 

//******************************************************************************

//******************************************************************************

/*! @page history History Log

 

@section history_0_1_beta  Версия 0.1.beta (в разработке)

 

@subsection history_101206  Промежуточная версия 101206

 

Для пущей ясности (относительно разбивки на dll и плагины) косметически

поправил чуть не каждый файл.

 

В классы устройств внесена правка, необходимая для согласования с остальными

изменениями ядра и структуры, и кое-какая косметика. Поправки простенькие и

локализованные, но полезно сравнить с исходными версиями и посмотреть, что и

как. А если окажется, что я правил уже устаревшую версию, то слить

аккуратненько.

 

 

Диме: Если бы у меня были свежие и хотя бы компилирующиеся версии Ваших текстов, я бы и их поправил.  Обратите внимание на изменения в sUniScanner и sPetrovich (для чего полезно уметь сравнивать текстовые файлы) и внесите изменения в свои производные и/или клоны от этих классов.

 

Обоим: Плагин Feofilov у вас в совместной разработке.  Договоритесь о дисциплине и держите меня в курсе - хотелось бы иметь представление о том, what is whose.

 

 

@subsection history_101202a  Промежуточная версия 101202a

 

Внедрены плагины, что потребовало реструктуризации программы: изменена

структура каталогов и проектов, программа развалена на части (exe, dll-ки ядра

и dll-ки плагинов).

 

Внедрены физ.величины (sPhysValue): расширенные вещественные числа (с

плюс-минус бесконечностью и неопределённостью), имеющие погрешность и единицы

измерения. Пока только основы, для конечного юзера незаметные, а для

программера необременительные (небольшие изменения при записи/чтении в/из БД).

Далее предстоит постепенно перейти к их использованию везде, где можно и нужно.

 

Кое какие переименования и переразбивка на файлы (для пущей читаемости текстов).

 

Добавлены базовые типы узлов RANet: sPhysValueNode sPhysRangeNode sBooleanNode

а вот просто вещественные числа в БД теперь не записываются. Тип real в

программе, конечно, останется, но будет использоваться там, где важна

эффективность.

 

Наряду с sArrayFunction теперь имеется sPairSetFunction - таблично заданная

зависимость с произвольным шагом по абциссе, динамически изменяющимся числом

точек и произвольным порядком их добавления (при этом они упорядочиваются по

абциссе).

 

@subsection history_lost  Предыстория

 

Утеряна

 

 

*/

 

//******************************************************************************

//******************************************************************************

/*! @page distrib Distribution

 

Порядок выпуска официальной версии:

- Вдумчивое слияние

- Полная пересборка под Windows и Linux в конфигурации Release

- Компиляция help'а

- Правка и компиляция перевода (linguist)

- Компиляция документации разработчика (doxygen)

- @ref distrib_form

- Инсталяция и тестирование дистрибутива на разных машинах и системах

- Увеличение номера версии для дальнейшей разработки

 

 

@section distrib_form Формирование дистрибутива

 

На данный момент для win32 минимальная процедура такая:

 

Пусть исходники лежат в некой папке <i>RAPROG</i>

(у меня это "d:\Vik\Prog\QtRA"),

а Qt установлен в <i>QTDIR</i>

(у меня это "с:\Qt\2009.05").

 

Всё ставится в некую папку <i>RADIST</i>, в имя которой полезно включить

номер версии (например,  "d:\RA_0_2") - тогда можно поставить рядом

вторую версию, попробовать, а потом уже перейти к работе на ней,

скопировав туда рабочую базу данных.

 

   Из папки <i>QTDIR</i>\\qt\\bin (НЕ ПУТАТЬ С <i>QTDIR</i>\\bin !!!)

   в папку <i>RADIST</i>\\bin

- assistant.exe

- libgcc_s_dw2-1.dll

- mingwm10.dll

- phonon4.dll

- QtCLucene4.dll

- QtCore4.dll

- QtGui4.dll

- QtHelp4.dll

- QtNetwork4.dll

- QtSql4.dll

- QtWebKit4.dll

- QtXml4.dll

- QtXmlPatterns4.dll

 

   Из папки <i>QTDIR</i>\\qt\\plugins\\sqldrivers

                 (НЕ ИЗ <i>QTDIR</i>\\bin\\sqldrivers !!!)

   в папку <i>RADIST</i>\\bin\\plugins\\sqldrivers

- qsqlite4.dll

 

   Из папки <i>RAPROG</i>\\bin

   в папку <i>RADIST</i>\\bin

- ra.exe

 

 

   Из папки <i>RAPROG</i>

   в папку <i>RADIST</i>

- License.html

- Manual.html

- и папку help целиком со всеми файлами и вложенными папками

 

 

   Из папки <i>RAPROG</i>\\locales

   в папку <i>RADIST</i>\\locales

- RA_ru.qm

 

 

*/

 

//******************************************************************************

//******************************************************************************

/*! @page datanet RANet Knowledgebase

 

 

 

*/

 

//******************************************************************************

//******************************************************************************

/* МУСОР

 

 

@section intro_sec Introduction

 

This is the introduction.

 

@section sec_projects Versions, Customizations, Build Projects

 

@subsection sec_project_vers  Versions

 

Версия программы состоит из версии общего ядра, кастомизации и даты

сборки.

 

Версия ядра в виде major.minor будет расти общепринятым образом, отражая

изменения в формате данных (обязательно) и более или менее заметные

подвижки в общей функциональности.

 

Кастомизация идентифицирует состав сборки (какие исходные тексты в неё

закомпилячены) и обозначается коротким @b уникальным идентификатором,

образованным из имени "хозяина" экспериментальной установки и/или кликухи

самой установки.  Только не надо использовать неинформативные типа "MySetup",

серийные имена "RadioPAN" или (тем более!) "ДФС-24" -- гораздо лучше

"BursiaPan", например.

 

Дата автоматически заносится при @b полной сборке.

 

@subsection sec_project_cust  Customizations

 

В идеале все весьма различно выглядящие и функционирующие инсталяции

программы Research Assistant будут иметь один и тот же исполняемый файл,

а его конкретное поведение определяться конфигурационной составляющей

данных.  Такую кастомизацию будем называть "global".

 

В процессе разработки будут появляться кастомизированные версии, которые,

однако, должны стремиться слиться в экстазе со следующей версией "global".

 

@subsection project_RA  RA Project

 

Это то, что я сейчас пишу.  Сегодня она претендует на звание global.  Полное

название версии 0.1.global.

 

 

@subsection project_RA4BursiaPan  RA4BursiaPan Project

 

Если мне захочется поэкспериментировать, не ломая основную (глобальную и уже

вышедшую в тираж) версию, то я, возможно, создам такой проект.  Но буду писать

его так, чтобы в конечном итоге он влился в @ref project_RA.

 

Новые исходные тексты я помещу вместе с файлом RA4BursiaPan.pro в

папку RA4BursiaPan.  Там же весь мусор и результат компиляции.  Там же тестовая

база данных.

 

Если затею переделку парочки файлов из библиотеки @ref RANet, то, возможно,

скопирую их туда же (и подменю в проекте).  Но скорее всего, скопирую всю

библиотеку в RANet_BursiaPan.

 

@subsection project_Test_Com  Test_Com Project

 

Это то, что сейчас пишет Митя

 

@subsection project_RA4RIZ  RA4RIZ Project

 

Это то, что будет писать Митя для Русланы.  Когда он закончит, мы сольёмся (в

экстазе, само-собой) и отнесём клиенту версию 1.0.global.  После чего он может

развивать версию 1.1.RIZ и/или начать версию 1.1.DN.

 

@subsection sec_cust_numbering  Динамика версий

 

Minor-компонента версии изменяется при  каждой выдаче версии в эксплуатацию

на "боевых" данных (на реальных, имеющих ценность спектрах), даже если её

получают не все пользователи, а только самые смелые.

 

Major-компонента версии увеличивается, как это принято, при значительных

изменениях или просто, когда захочется создать повод для выпивки (именно

поэтому версия 0.1 превращается сразу в 1.0 при первой сдаче в эксплуатацию).

 

Ниже приведён возможный сценарий развития с разбором нюансов:

- @b 0.1.global + @b project_Test_Com ---> @b 0.1.global

  (промежуточное слияние, в эксплуатацию не идёт)

- @b 0.1.global + @b 0.1.BursiaPan + @b 0.1.RIZ ---> @b 0.1.global

  (промежуточное слияние; формат данных, возможно, изменился по инициативе одного

  из разработчиков, врезультате чего БД другого разработчика, порождённая

  предыдущей подверсией

  версии 0.1, уже не читается новой подверсией версии 0.1.global, но это была

  тестовая БД, её не жалко; обеспечивается читаемость только предыдущих версий,

  сданных в эксплуатацию)

- @b 0.1.global + @b 0.1.BursiaPan + @b 0.1.RIZ ---> @b 1.0.global

  (@b в @b эксплуатацию; порождаемые данные получают тэг "v.1.0.global")

- @b 1.0.global + @b 1.1.BursiaPan + @b 1.1.RIZ ---> @b 1.1.global

  (промежуточное слияние)

- @b 1.1.global + @b 1.1.BursiaPan + @b 1.1.RIZ ---> @b 1.1.global

  (промежуточное слияние)

- . . .

- @b 1.1.global + @b 1.1.BursiaPan + @b 1.1.RIZ --->

  @b 1.1.global + @b 1.2.BursiaPan + @b 1.1.RIZ

  (я рискнул инсталлировать версию 1.1.BursiaPan у себя на "боевой" БД;

  теперь мои данные получают тэг "v.1.1.BursiaPan", а версия в разработке

  переименована в 1.2.BursiaPan)

- @b 1.1.global + @b 1.2.BursiaPan + @b 1.1.RIZ ---> @b 1.2.global

  (промежуточное слияние)

- @b 1.2.global + @b 1.2.BursiaPan + @b 1.2.RIZ ---> @b 1.2.global

  (промежуточное слияние)

- @b 1.2.global + @b 1.2.BursiaPan + @b 1.2.RIZ --->

  @b 1.2.global + @b 1.3.BursiaPan + @b 1.2.RIZ

  (тестируя свою версию, я случайно записал ценный спектр; он имеет тэг

  "v.1.2.BursiaPan", но лежит в тестовой БД; я заархивировал тестовую БД,

  экзэшник, и все исходники, после чего переименовал версию в разработке;

  как я потом засуну этот спектр в боевую БД - это вопрос отдельный,

  но теоретическая возможность обеспечена, и уж, как минимум, я всегда смогу

  посмотреть его на экране и экспортировать в двухколоночный текст)

- @b 1.2.global + @b 1.3.BursiaPan + @b 1.2.RIZ ---> @b 1.3.global

  (промежуточное слияние)

- . . .

- @b 1.3.global + @b 1.3.BursiaPan + @b 1.3.RIZ ---> @b 1.4.global

  (@b в @b эксплуатацию)

- @b 1.4.global + @b 1.5.BursiaPan + @b 1.5.RIZ ---> @b 1.5.global

  (промежуточное слияние)

- . . .

 

 

@subsection project_RAdmin  RAdmin Project

 

Это внутреннего пользования упрощённый проект --

утилита для просмотра и редактирования сети.

 

 

@section sec_naming Naming conventions

 

@subsection sec_naming_classes Classes

 

sMyClass

 

xMyExceptionClass

 

nNetValueClass

 

@subsection sec_naming_types Other types

 

tName2CodeMap

 

Exception is made for few simple and very common typedefs in General.h:

- literal = константный указатель на константный массив символов

- real = long double

- ...

 

 

@subsection sec_naming_class_members Class members

 

Приставка @a The используется, когда

имеется приватный член @a TheMember, доступ к

которому прикрыт публичной функцией

@a Member() и, возможно, функцией @a SetMember(...).

 

 

@section datanet Datanet

 

 

 

*/