This is a file to read if you want to join the KLog development team.

This document will explain the KLog architecture, requirements, tips and important to know
things to take into account when joining the KLog development team.



CONTENT:
1 - BEFORE CODING
2 - KLOG ARCHITECTURE
3 - BEFORE CODING
4 - CODING
5 - AFTER CODING
6 - GUI
7 - DOCUMENTATION
8 - TRANSLATIONS
9 - DEPLOYING


1 - BEFORE CODING:

Read this document.

Join the KLog Telegram group and say hello.
Once the number of developers grow, I will create a Telegram group or mailing list for developers.

Interesting links:
http://www.qtcentre.org/wiki/index.php?title=Keeping_the_GUI_Responsive
Packer: http://upx.sourceforge.net/



= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

2 - KLOG ARCHITECTURE

KLog is intended to be a MODULAR software with the requirement to be modular ;-) so it is easy to
add new features (mainly contests and awards support).

2.1 IMPORTANT THINGS TO HAVE IN MIND

DEPRECATED - KLog version number is using the following system:
   Release versions: 2.4, 2.5, ... 2.4.1, 2.4.2, ...
   There are Release Critical versions that will be released before an official release for testing purposes.
   Release Critical versions are like: 2.4.2-RC1, 2.4.2-RC2, ...
   The release number is defined in the "version.h.in" file.

- KLog should manage several logs. The "log" table of the DB has a column called "lognumber".
   ALL QSO has a lognumber id that identifies the log it belongs to.
   Each lognumber will have associated a Name and/or ID (TBD) so the user is able to "open" just
   that log. It is important that all the QSO operations are aware of this lognumber id.

- The log table has a "marked" column. This column is to allow mass operations. Changing this column has
  to be done with care and leave it "unmarked" once the desired operation is finished.
  KLog should unmark(N) all QSO when starts and exits. Mark = 'X', unmark='N' or other.
  Marked column should not be saved.

- Any change to the DB architecture must be communicated and agreed with the development team before
  commiting to the SVN and following the 2.4 DB UPDATES area in this document.



2.3 AWARD SUPPORT

2.4 DB UPDATES

A DB update consist on:

- All the intended changes.
- Update the softwarecontrol TABLE on the DB

To update the DB structure there are several things to have in mind:

- The current version of the DB is defined in database.h
    const float DBVersionf = 0.003;

- All the actions to update the DB to the new structure are done here:
    DataBase::updateIfNeeded

- After making any update



= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

3 - BEFORE CODING

Update your sources from the Github: Remember that other developer may has done a commit.

3.0 - Common development environment

KLog is being developed using:
 - Qt 6.8.3
 - Hamlib 4.6.3

Versions of Qt are upgraded together with Debian testing. KLog development can't be ahead of Debian testing to prevent we use a version
that is not deployed in Debian stable and therefore we make KLog not available in all the Debian derivative versions (Ubuntu, ...)
Same should be taken into consideration for hamlib.

3.1 - Linux development environment
3.2 - macOS development environment
3.3 - Windows development environment
  KLog is being developed using Qt Creator 17.0.0.
  Using Qt Maintenance Tool, install:
  
  + Qt
    - Qt 6.8.3
	- MinGW 13.1.0 64 bits
	- Additional Libraries:
	  - Qt Charts
	  - Qt Location
	  - Qt Positioning
	  - Qt Serial Port
	
  +Build Tools
    - CMake
	- Ninja
	- MinGW 13.10.0 64bit
	- OpenSSL 3.0.16 Toolkit

After installing the previous software, KLog can be also developed with Visual Studio Code.

= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

4 - CODING

- The development language is English.
- All Strings to be shown to the user must be translatable. i.e. tr("String")

4.1 - STYLE
4.2 - ADIF SUPPORT

KLog is using some application defined ADIF fields: APP_{PROGRAMID}_{FIELDNAME}

Header fields:
    APP_KLOG_LOG_DATE_EXPORT: The date and time (in UTC) when the log was exported.
    APP_KLOG_QSOS: The number of QSOs in the log.
    DEPRECATED: APP_KLOG_RELEASE: Release of KLog used to export the log file. CHANGED TO PROGRAMVERSION (ADIF standard)

QSO fields:
    APP_KLOG_POINTS: Points given by the QSO.
    APP_KLOG_LOGN: Lognumber if the ADIF file contains several logs.


KLog is also importing other application defined ADIF fields:
    APP_N1MM_POINTS: That is imported into the points column in the log table.

KLog should not export any ADIF header that comming from other application without renaming it to APP_KLOG_

4.3 SHORTCUTS

Before adding or modifying any shortcut:
 - It should be agreed in the devel mailing list.
 - It should be as standard as possible, reuse the same shortcuts of main/popular contest software.
 - It should be checked and added to a list below.



4.4 DATA BASE

- The DB version has to be checked and modified after a DB schema modification.
- Any modification to the DB has to be provided with the code to update from any previous version.

4.5 MODE & SUBMODE

The UI should show always the SUBMODE in the main widget.
QSOs should save mode & submode.
If no submode is present, KLog should save the first "mode" where mode & submode are the same.
On export, mode & submode should be exported.

= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

5 - AFTER CODING

Test that your code compiles and does not break the previous code.

Document your changes and close/update the tasks/bugs you have worked on.

Remember to commit your code to the SVN.

Try to do "atomic" commits. That is to commit updates that may be disabled as a block.
i.e. A new function or a modification to a function. Don't commit several things at once
if you can avoid it.
This is just a recommendation to avoid big commits that, in case of a problem are difficult to
trace.

Document your commits: ALWAYS add a clear comment to the commits so it is easy to know what is it about.

5.1 TEST CHECKLIST

Here is the list of tests to be done before releasing new software:

 - Install in a new installation of Windows/macOS
 - Upgrade from a previous version

 - Create a new log
 - Add a new QSO
    - Check that the DXCC & IOTA continent make sense
    - Check if QSO/worked DXCC, ... count changes
 - Edit a QSO from log
    - Modify at least one field in each tab
 - Edit a QSO from the search box
 - Remove a QSO
 - Update the DXCC status tab


 - Connect to the DXCluster
 - Click on a spot on the DXCluster

 - Export an ADIF file
 - Import an ADIF file

 - Remove KLog in Windows




= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

6 - GUI

6.1 CONTEST GUI

- The GUI should only have the data fields that are needed for that contest, keeping the GUI simple
  and easy to use.



= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

7 - DOCUMENTATION

- One feature will not be considered completed until it is not added to the user manual.
  Please document in the klog-handbook.xml your feature so the user knows how to use it.

= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

9 - TRANSLATIONS

9.1 ADDING TRANSLATIONS

To add a new translation add the new language file to the klog.pro file following the sintax:

TRANSLATIONS = KLog_es.ts \
    klog_fr.ts

Being es, fr, the ISO codes naming the language.

After a translation is added, you also need to update the aboutdialog.cpp to include a new Translator line.

9.2 TRANSLATING

Translators should work in the *.ts files.

9.2 UPDATING TRANSLATIONS

Update translations:
  Run: lupdate -verbose klog.pro
  in the klog directory to update the language files

= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

9 - DEPLOYING

Before deploying, translations should be updated.


9.1 DEPLOYING ON LINUX

9.2 DEPLOYING ON macOS

    Build KLog with QTCreator
    If you can't run KLog due to missing libTIFF/LibJPEG/libPNG/libGIF chec this URL:
    https://stackoverflow.com/questions/35509731/dyld-symbol-not-found-cg-jpeg-resync-to-restart
    Try this in the shell:
        $ cd /System/Library/Frameworks/ImageIO.framework/Versions/A/Resources
        $ sudo ln -sf libJPEG.dylib /usr/local/lib/libJPEG.dylib
        $ sudo ln -sf libPng.dylib /usr/local/lib/libPng.dylib
        $ sudo ln -sf libTIFF.dylib /usr/local/lib/libTIFF.dylib
        $ sudo ln -sf libGIF.dylib /usr/local/lib/libGIF.dylib

    Run the following command from the build directory:
        mv klog.app KLog.app
        create new folder in KLog.app/Contents/PlugIns/sqldrivers
        copy $QT_DIR/plugins/sqldrivers/libqsqlite.dylib to the new folder (/Developer/Applications/Qt/plugins/)
        create new folder: KLog.app/Contents/MacOs/translations
        copy the *.qm (translation) files into KLog.app/Contents/MacOS/translations
        macdeployqt KLog.app/ -dmg
        mv KLog.dmg KLog-[VERSION].dmg

9.3 DEPLOYING ON WINDOWS
    Currently using an Open Source Licence of: BitRock InstallBuilder

9.4 ICON
    Follow this link for all the OS:
    http://doc.qt.io/qt-5/appicon.html

Installer:
http://en.wikipedia.org/wiki/List_of_installation_software

