ARK2/Technical - Revision history

John Layt: /* Supported Platforms */

2021-09-21T15:40:34Z

‎Supported Platforms

John Layt: /* Custom Forks */

2018-04-27T09:30:40Z

‎Custom Forks

John Layt: /* Custom Forks */

2018-04-27T09:29:08Z

‎Custom Forks

John Layt: /* Custom Forks */

2018-04-26T12:11:00Z

‎Custom Forks

John Layt: /* Branching Strategy */

2018-04-26T12:08:59Z

‎Branching Strategy

John Layt: /* Custom Forks */

2018-04-26T11:57:46Z

‎Custom Forks

John Layt: /* Custom Forks */

2018-04-26T11:49:17Z

‎Custom Forks

John Layt: /* Git / Github */

2018-04-26T11:39:23Z

‎Git / Github

John Layt: /* Git / Github */

2018-04-25T09:15:52Z

‎Git / Github

John Layt at 14:35, 12 August 2017

2017-08-12T14:35:17Z

@@ Line 6: / Line 6: @@
 * Apache is supported and will require mod_rewrite, other servers may work.
-* PHP: PHP 7.1 is required due to new language features. In future the minimum version will be the minimum supported by PHP (see in [http://php.net/supported-versions.php PHP Supported Versions].
+* PHP: PHP 7.4 is required due to new language features. The minimum version will be the minimum supported by PHP (see in [http://php.net/supported-versions.php PHP Supported Versions].
 * PHP intl extension and ICU will be required, the opcache and APCu cache extensions are strongly recommended for performance.
-* MySQL/MariaDB v5.5 or later (lowest supported MySQL, 5.5 for timestamps, 5.6 for full-text index, 5.7.5 for spatial index), utf8mb4 codeset only
+* MySQL/MariaDB v5.7.8 or later (lowest supported MySQL, required for timestamps, full-text index, spatial index, and JSON type), utf8mb4 codeset only
-* PostgreSQL v9.2 or later
+* PostgreSQL v10 or later
-* SQLite 3.7.11 or later (required for multiple inserts)
+* SQLite 3.9 or later (required for multiple inserts, full-text index, JSON type), Spatialite extension for spatial data
 * Redis is recommended for data caching
 * Linux and Mac are actively supported, Windows is also supported but minimally tested

@@ Line 109: / Line 109: @@
 * Add the arklab/arkserver repository as a git remote
 * Create a '''dev''' branch tracking a formal release branch on arklab/arkserver
-* Create a '''qa''' branch tracking the '''dev''' branch
+* Create a '''test''' branch tracking the '''dev''' branch
-* Create a '''prod''' branch tracking the '''qa''' branch
+* Create a '''prod''' branch tracking the '''test''' branch
 * All custom code development occurs on the '''dev''' branch
 * When custom code is stable for deployment to test server the '''dev''' branch is merged into the '''test''' branch

@@ Line 109: / Line 109: @@
 * Add the arklab/arkserver repository as a git remote
 * Create a '''dev''' branch tracking a formal release branch on arklab/arkserver
-* Create a '''prod''' branch tracking the local '''dev''' branch
+* Create a '''qa''' branch tracking the '''dev''' branch
 * All custom code development occurs on the '''dev''' branch
-* When custom code is stable for deployment to production the '''dev''' branch is merged into the '''prod''' branch
+* When custom code is stable for deployment to test server the '''dev''' branch is merged into the '''test''' branch
 * Production hotfixes can be developed on '''prod''' or a branch forked from '''prod'''
-* When a new ARK Server version is released the '''dev''' branch is rebased onto the new remote release branch for testing and then merged forward
+* When a new ARK Server version is released the '''dev''' branch is rebased onto the new remote release branch for testing and then merged forward for testing
-* Production deployment will usually be a clone of the development repository checked-out to the '''prod''' branch and rebased when new production releases occur. Prod config settings may be committed to the repo here.
+* Test server deployment is a clone of the dev repository checked-out to the '''test''' branch and rebased when new test releases occur. Test config settings may be committed to the repo here.
-The git commands required to set this up are:
+The steps to set this up on GitLab are:
-* Either clone an empty project created on GitLab or create a new local repository
+* Create the new project
 * git remote add arklab git@gitlab.com:arklab/arkserver.git
 * git fetch arklab
 * git branch -t dev arklab/master
-* git branch -t prod dev
+* git branch -t test dev
 * git checkout dev

@@ Line 114: / Line 114: @@
 * Production hotfixes can be developed on '''prod''' or a branch forked from '''prod'''
 * When a new ARK Server version is released the '''dev''' branch is rebased onto the new remote release branch for testing and then merged forward
-* Production deployment will usually be a clone of the development repository checked-out to the '''prod''' branch and rebased when new production releases occur
+* Production deployment will usually be a clone of the development repository checked-out to the '''prod''' branch and rebased when new production releases occur. Prod config settings may be committed to the repo here.
 The git commands required to set this up are:

@@ Line 90: / Line 90: @@
 We will use a simplified version of the [https://wiki.qt.io/Branch_Guidelines Qt git workflow].
 * '''master''' branch is the semi-stable development branch for the next release which should always be in a stable enough state to pass CI testing
 * New feature or bugfix branches for the next release are branched off '''master''' prefixed with the name of the author/group/client and including the feature or bug number, e.g. '''jlayt/linked-data''' or '''jlayt/issue-1234'''
 * Once a new feature is finished and passes testing, it is rebased onto the current '''master''' and merged via a merge request with review
@@ Line 99: / Line 98: @@
 * Any bugfixes for the stable release will be made in the earliest release branch they apply to and then merged forward through each release then eventually into '''master''' (merges may be immediate or periodic depending on the volume)
 * Bugfix branches for the stable release are branched off the release branch prefixed with the name of the branch and including the feature or bug number, e.g. '''fix/2.1/issue-1234'''
 === Custom Forks ===

@@ Line 78: / Line 78: @@
 * http://culttt.com/2014/05/07/create-psr-4-php-package/
-== Git / Github ==
+== Project Management ==
-Development is hosted on [https://github.com/lparchaeology Github], so you will need a free Github account to contribute code.
+The ARK project is hosted on [https://gitlab.com/ GitLab], so you will need a free GitLab account to contribute to development. Bug reports may be opened using a Google or Facebook account. The code is also mirrored on GitHub.
-If you are new to Git, you may find the [https://desktop.github.com/ Github desktop application] easier to use. Alternatives are [https://www.sourcetreeapp.com/ SourceTree] and [https://www.gitkraken.com/ GitKraken].
+The umbrella ARK project is organised under the [https://gitlab.com/arklab @arklab] group on GitLab, which includes the [https://gitlab.com/arklab/arkserver ARK Server] project. All public development and supported releases occur in this project repository. All code, issues, and wiki documentation on this project are public. All code contributions must pass formal code review before being merged. A separate GitLab group for [https://gitlab.com/lparchaeology L - P : Archaeology] manages private client forks and deployments of ARK Server.
-We will use a simplifed version of the [https://wiki.qt.io/Branch_Guidelines Qt git workflow].
+GitLab provides a very powerful web application for managing projects, but most local development is done using the standard git command line tools. If you are new to Git, you may find a desktop application easier to use. Options include [https://www.sourcetreeapp.com/ SourceTree], [https://www.gitkraken.com/ GitKraken], and [https://desktop.github.com/ Github desktop].
 * '''master''' branch is the semi-stable development branch for the next release which should always be in a stable enough state to pass CI testing
 * New feature or bugfix branches for the next release are branched off '''master''' prefixed with the name of the author/group/client and including the feature or bug number, e.g. '''jlayt/linked-data''' or '''jlayt/issue-1234'''
 * Once a new feature is finished and passes testing, it is rebased onto the current '''master''' and merged via a merge request with review
@@ Line 94: / Line 99: @@
 * Any bugfixes for the stable release will be made in the earliest release branch they apply to and then merged forward through each release then eventually into '''master''' (merges may be immediate or periodic depending on the volume)
 * Bugfix branches for the stable release are branched off the release branch prefixed with the name of the branch and including the feature or bug number, e.g. '''fix/2.1/issue-1234'''
 == Folder Structure ==

@@ Line 85: / Line 85: @@
 We will use a simplifed version of the [https://wiki.qt.io/Branch_Guidelines Qt git workflow].
-* '''dev''' branch is the semi-stable development branch for the next release
+* '''master''' branch is the semi-stable development branch for the next release which should always be in a stable enough state to pass CI testing
-* New feature or bugfix branches are branched off '''dev''' with the name of the author/group/client and the feature or bug number, e.g. '''jlayt/linked-data'''
+* New feature or bugfix branches for the next release are branched off '''master''' prefixed with the name of the author/group/client and including the feature or bug number, e.g. '''jlayt/linked-data''' or '''jlayt/issue-1234'''
-* Once a new feature is finished and passes testing, it is rebased onto the current '''dev''' and merged via a Github merge request with review
+* Once a new feature is finished and passes testing, it is rebased onto the current '''master''' and merged via a merge request with review
-* Alpha and Beta testing releases will be tagged on '''dev''' and not branched
+* Alpha and Beta testing releases will be tagged on '''master''' and not branched
-* Once '''dev''' is deemed feature complete and stable enough for a Release Candidate then a release branch will be branched off '''dev''' with the minor release number, e.g. '''release/2.0''', '''release/2.1''', etc
+* Once '''master''' is deemed feature complete and stable enough for a Release Candidate then a release branch will be branched off '''master''' with the minor release number, e.g. '''release/2.0''', '''release/2.1''', etc
 * Further testing will take place on the release branch, with fixes applied to to the release branch as required
-* Once ready for release, the release will be tagged with the point release number (e.g. 2.0.0) and all bugfixes merged back into '''dev'''
+* Once ready for release, the release will be tagged with the point release number (e.g. 2.0.0) and all bugfixes merged back into '''master'''
-* Any bugfixes for the stable release will be made in the earliest release branch they apply to and then merged forward through each release then eventually into '''dev''' (merges may be immediate or periodic depending on the volume)
+* Any bugfixes for the stable release will be made in the earliest release branch they apply to and then merged forward through each release then eventually into '''master''' (merges may be immediate or periodic depending on the volume)
 == Folder Structure ==

@@ Line 6: / Line 6: @@
 * Apache is supported and will require mod_rewrite, other servers may work.
-* PHP: PHP 7 is required, minimum version will be the minimum supported (see in [http://php.net/supported-versions.php PHP Supported Versions].
+* PHP: PHP 7.1 is required due to new language features. In future the minimum version will be the minimum supported by PHP (see in [http://php.net/supported-versions.php PHP Supported Versions].
-* PHP intl extension and ICU will be required, the APCu cache extension is strongly recommended for performance.
+* PHP intl extension and ICU will be required, the opcache and APCu cache extensions are strongly recommended for performance.
 * MySQL/MariaDB v5.5 or later (lowest supported MySQL, 5.5 for timestamps, 5.6 for full-text index, 5.7.5 for spatial index), utf8mb4 codeset only
 * PostgreSQL v9.2 or later
@@ Line 13: / Line 13: @@
 * Redis is recommended for data caching
 * Linux and Mac are actively supported, Windows is also supported but minimally tested
 == Standards ==
@@ Line 24: / Line 39: @@
 * [http://symfony.com/doc/current/components/http_foundation.html Symfony HTTP Foundation] for interchangeable Request/Response objects
 * [http://www.php-fig.org/psr/psr-7/ PSR-7] HTTP Message Interface for interchangeable Request/Response objects if required for some components
-* HTML5 / CSS3 ES?
+* HTML5 / CSS3 ES vTBD
 * All files will be UTF8 using UNIX LF
@@ Line 53: / Line 67: @@
 == PHP Autoloading ==
-PSR-4 is used for packaging, namespace and auto-loading of OO code.
+PSR-4 is used for packaging, namespace and auto-loading of code.
 * [https://getcomposer.org/ Composer] will be required for dependency management and PSR-4 auto-loading
 * All external libraries will be installed by Composer under vendor/
-* All OO classes will be namespaced under ARK\
+* All code to be Object Oriented and implemented using a namespace of ARK
-* All OO code will be under src/
+* All code will be under src/<namespace>
 A good series of articles explaining PSR-4 and modern development and packaging in general can be found at the following:
@@ Line 100: / Line 114: @@
 * The 'build' folder holds tools and source files for building [[ARK2/Frontend|frontends]]
 * The 'sites' folder holds the site specific files in a way that supports multi-site installs
-* The 'src' folder holds the ARK source code
+* The 'src' folder holds the namespaced source code, e.g. src/ARK, src/MySite, etc
 * The 'tests' folder holds the ARK auto-tests
-* The 'var' folder holds transitory files, such as install-wide caches and logs
+* The 'var' folder holds install-wide transitory files, such as caches and logs (site-specific go in the site folder)
 * The 'vendor' holds the component library code managed by Composer
-Tarball packaging for release will not include the 'build' or 'test' folders, nor the contents of the 'vendor' folder.
+Tarball packaging for release will not include the 'build', 'test', or 'vendor' folders.
 The ARK2 'src' folder is organised as follows:
@@ Line 141: / Line 155: @@
         |- console
       |- config/
         |- database.json
         |- site.json
@@ Line 150: / Line 165: @@
       |- translations/
         |- <frontend>/
       |- web/
         |- .htaccess