Difference between revisions of "ARK2/Technical"

From ARK
Jump to: navigation, search
(→‎File Structure)
(→‎File Structure)
Line 77: Line 77:
 
* 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 '''dev''' (merges may be immediate or periodic depending on the volume)
  
−
== File Structure ==
+
== Folder Structure ==
  
−
The following file structure will be used, based on the default Silex and Composer structure, but adapted to support multi-site and multi-tenant.
+
The following folder structure is used by ARK2, based on the default Silex and Composer structure, but adapted to support multi-site and multi-tenant.
−
* The web root will be in /web/
+
 
−
* The ARK source code will be in /src/ organised by source type (php, js)
+
* The 'bin' folder holds any executable binaries, primarily the admin console script
−
* Composer installs external PHP packages into /vendor/
+
* The 'build' folder holds tools and source files for building [[ARK2/Frontend|frontends]
−
* NPM installs Node packages into /build/node_packages/
+
* The 'sites' folder holds the site specific files in a way that supports multi-site installs
−
* Bower will be configured to install external packages into /build/vendor/
+
* The 'src' folder holds the ARK source code
−
* The ARK and custom theme assets will be in /build/themes/<name>/ organised by source type (js, sass, etc)
+
* The 'tests' folder holds the ARK auto-tests
−
* Compiled theme bundles will be written into /web/themes/<name>/
+
* The 'var' folder holds transitory site files, such as caches and logs
−
* Custom code will be in ???
+
* The 'vendor' holds the component library code managed by Composer
−
* Packaging for release will not include the /build/ or /test/ directories
+
 
 +
Tarball packaging for release will not include the 'build' or 'test' folders, nor the contents of the 'vendor' folder.
  
 
  /
 
  /

Revision as of 21:21, 3 December 2016

Technical Details

Platforms

  • HTML5 will be used
  • Browser support restricted to those supported by Bootstrap 3
  • PHP: A minimum of v5.6 will be supported (5.6 is in Security Support, 5.7 in active support, see http://php.net/supported-versions.php), v7 will be supported.
  • MySQL/MariaDB v5.5 or later (lowest supported MySQL) (5.6 for full-text index, 5.7.5 for spatial index)
  • PostgreSQL v9.2 or later
  • SQLite 3.7.11 or later (required for multiple inserts)
  • mod_rewrite will be required
  • PHP intl extension and ICU will be required

Standards

The PHP-FIG standards will be used:

  • PSR-1 and PSR-2 Coding Standards
  • PSR-3 Logging Interface for interchangeable logging objects
  • PSR-4 Auto-Loading Standard
  • PSR-5 PHPDoc Standard (proposed)
  • Symfony HTTP Foundation for interchangeable Request/Response objects
  • PSR-7 HTTP Message Interface for interchangeable Request/Response objects if required for some components
  • All files will be UTF8 using UNIX LF

Plugins are available for Eclipse, Atom, and other IDEs to automatically check and/or apply these standards.

Framework and Components

The chosen framework is the Silex micro-framework built using Symphony components

Components will be carefully chosen to be well supported, stable, and interchangeable wherever possible. A number of criteria will be applied in selection:

  • Must be standards compliant
  • Must be well supported with a solid development history
  • Must be well documented
  • Must be widely used and supported
  • Must have a strong community, small one-person efforts will only be considered if they are the de-facto standard
  • Any database access must use Doctrine DBAL or ORM

Significant and reliable sources of components include:

  • User frosting, a UserCake fork with RBAC user management, using Slim2, SBAdmin2, use for ideas

PHP Autoloading

PSR-4 is used for packaging, namespace and auto-loading of OO code.

  • 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 OO code will be under src/

A good series of articles explaining PSR-4 and modern development and packaging in general can be found at the following:

Git / Github

Development is hosted on Github, so you will need a free Github account to contribute code.

If you are new to Git, you may find the Github desktop application easier to use. Alternatives are SourceTree and GitKraken.

We will use a simplifed version of the Qt git workflow.

  • dev branch is the semi-stable development branch for the next release
  • 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
  • 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
  • Alpha and Beta testing releases will be tagged on dev 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
  • 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
  • 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)

Folder Structure

The following folder structure is used by ARK2, based on the default Silex and Composer structure, but adapted to support multi-site and multi-tenant.

  • The 'bin' folder holds any executable binaries, primarily the admin console script
  • 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 'tests' folder holds the ARK auto-tests
  • The 'var' folder holds transitory site files, such as caches and logs
  • 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. 

/
|- bin/
  |- console
|- build/
  |- <see Frontend>
|- sites/
  |- <site>/
    |- config/
      |- database.json
      |- site.json
    |- files
      |- <see Files>
    |- src/
      |- <see Frontend>
    |- schema/
    |- web/
      |- <see Frontend>
|- src/
  |- ARK/
    |- server/
      |- php/
      |- schema/
        |- database/
        |- json/
    |- web/
      |- <see Frontend>
|- tests/
|- var/
  |- cache/
  |- logs/
|- vendor/

Environment

To develop ARK requires the following tools to be installed:

You will also require PHP, a web server (Apache/PHP), a database server (MySQL/PostreSQL/SQLite), a web browser (Chrome/Firefox), and a an API client (Postman).

The following tools are recommend to adhere to ARK code quality standards:

  • php-cs-fixer
  • PHP CodeSniffer
  • PHP MD

macOS

On macOS, while you can install the requirements via standalone packages, we recommend using HomeBrew as it makes installing and updating all the tools used easier.

  • Install XCode
  • Install the Command Line Tools (includes Git)
  • Download and install HomeBrew
  • brew install node tidy-html5 homebrew/php/composer homebrew/completions/composer-completion homebrew/php/php-cs-fixer homebrew/php/php-code-sniffer homebrew/php/phpmd homebrew/php/sqlformat homebrew/php/phplint
  • npm install -g bootlint csscomb csslint eslint js-beautify jsonlint prettydiff remark-lint sass-lint tidy-markdown
  • (Optional) Modify your .profile to enable command-line auto-complete
export HOMEBREW_GITHUB_API_TOKEN="token"
source /Library/Developer/CommandLineTools/usr/share/git-core/git-completion.bash
source /Library/Developer/CommandLineTools/usr/share/git-core/git-prompt.sh
GIT_PS1_SHOWDIRTYSTATE=true
PS1='\u@\h \W$(__git_ps1 " (%s)") \$ '
export PATH=/Users/odysseus/.bin:$PATH

The easiest way to run a webserver and database server is using MAMP. Simply install MAMP and create a soft-link from the MAMP webroot to the location of your ARK git repository. The alternative is to use HomeBrew to configure and run your own install. The HomeBrew method is recommended for developing with PostgreSQL (TODO). 

  • brew install homebrew/php/php70 homebrew/php/php70-tidy homebrew/php/php70-xdebug


For QGIS Python:

  • 'brew install python qt pyqt'
  • 'pip install pep8 autopep8 jedi pb_tool '

TODO

  • xdebug setup
  • apache / php /mysql / mamp
  • linter/fixer rulesets

Atom Editor

While text editors and IDEs are a deeply personal choice, we recommend using Atom as it is a cross-platform Open Source editor with powerful plugins to support the tools used by ARK. Using Atom ensures you have an environment consistent with the core ARK developers and ARK development standards.

After installing Atom, check the commandline tools have been installed.

Recommended Atom Packages:

  • 'apm install atom-autocomplete-php atom-beautify atom-bootstrap3 atom-symfony2 autocomplete-sass doctrine linter-bootlint linter-csslint linter-eslint linter-jsonlint linter-markdown linter-php linter-phpcs linter-phpmd linter-sass-lint linter-tidy linter-twig php-composer-completion php-cs-fixer php-debug php-twig symfony-snippets'

Useful Atom Packages:

  • sublime-style-column-selection
  • autoclose-html
  • browser-plus
  • docblockr
  • git-plus
  • highlight-line
  • highlight-selected
  • minimap
  • open-recent
  • pigments
  • platformio-ide-terminal
  • project-manager
  • sort-lines
  • sync-settings
Retrieved from "https://ark.lparchaeology.com/wiki/index.php?title=ARK2/Technical&oldid=124469"