Building and maintaining customized versions of OpenPetra

see also Customizing OpenPetra

Purpose

Every organisation is different, so there cannot be one OpenPetra installation for all. It might work for smaller charities, for one country, but for bigger offices the default version of OpenPetra is not sufficient.

There must be a standard way to accomplish this, which will ensure that updates from upstream can be used in the customized version, and local improvements can be merged back into upstream if they would benefit other organisations as well.

Rules

• Never change a code file directly
• Changes to the code that benefit everyone must be merged into to upstream
• Custom files must be clearly identifiable, either by a special sub directory called "custom", or by file extension ".my"
• .config files are never committed to the source code repository. If a .config file exists, that will be used. Otherwise if a .my file exists, that is used

Customizing files

Build files

• The default config file for OpenPetra.build is stored in eg. OpenPetra.build-sample-win.config
• Usually, the file is copied to OpenPetra.build.config, and that file is not committed to the repository, since every developer will have different settings in that file.
• For a defined environment in an organisation or if the repository is only used by one developer, you can commit the file OpenPetra.build.config.my to your local repository, which would be picked up instead of OpenPetra.build.config if that does not exist. OpenPetra.build.config has higher priority than OpenPetra.build.config.my

Configuration files

Execute debug version by developer

• There are sample files which are located in the etc directory, eg. etc\Client.config.sample
• You can add your own customized files with the name Client.config.my etc. This will be used when running eg nant startPetraClient. Just make sure there is no Client.config file, because that would have higher priority than Client.config.my.

Configuration files for the installer

• The default configuration files are stored in the files setup\petra0300\remoteclientWin\PetraClientRemote.config and setup\petra0300\linuxserver\PetraServerConsole-mysql.config.
• Most server specific settings (port, URLs etc) should be set when building the installer, and can be defined as parameters on the command line.
• Some customization might be necessary for configuring plugins, eg. for authentication.
• Customized configuration files should be stored in the file PetraClientRemote.config.my or PetraServerConsole.config.my, and will be picked up by the nant tasks which build the installers.

Navigation files

• the default navigation file is csharp\ICT\Petra\Definitions\UINavigation.yml
• Currently, if there is a navigation file UINavigation.yml.my, the installers will use that file instead of the default UINavigation.yml file.
• In the future, it should be possible to derive from UINavigation.yml and to specify only changes to that file, both additions and omissions.

Translation files

• Translation files are stored in the directory i18n, eg. de-DE.po
• Texts can be overwritten to reflect the use of organisation specific terms. Such files with only the different texts are stored in eg. i18n\de-DE.po.my
• When running nant translationCompilePOFile, all language files (*.po) in i18n will be converted to a GNU Gettext resource dll, and the contents of *.po.my files will overwrite the specified texts per language.

Plugins

TODO

Report Parameter/Settings

TODO

Custom Reports

TODO

Changes to the UI dialogs

TODO

Building a release

• TODO build a release for server
• TODO build a release for client

nant buildReleaseWindowsClient -D:ReleaseID=0.2.3.0 -D:OrgName="Sample Charity" -D:PublisherUrl=www.openpetra.com -D:ServerHost=www.openpetra.com -D:ServerPort=3000

• TODO archive tar.gz file for building future patches
• TODO build a patch for the client