Skip to content

Latest commit

 

History

History
126 lines (110 loc) · 5.8 KB

introduction.rst

File metadata and controls

126 lines (110 loc) · 5.8 KB
Raw

Guidelines for Developers

is a collection of software, databases, and services coordinated and hosted by NOI techpark in Bolzano/Bozen, South Tyrol. Currently, systems are related to mobility and tourism. In the future might diversify into more fields.

Companies and developers contributing to must follow the guidelines listed in the documents as close as possible.

The aim of the Developer's Guidelines ("The Guidelines") is to simplify the hosting and maintenance of the software, databases, and services by the developers and maintainers at NOI Techpark ("the team").

The Guidelines describe the conventions to which a developer must adhere, to be able to become an active developer or to see his work being incorporated into the . They are split in two parts:

  • Platform Guidelines explain the preferred programming languages, how to expose the data after you manipulated them, the use of third-party libraries or plugins, and so on.
  • Database Guidelines clarify how to design a database that shall become part of the platform.

Both of them are summarised in the remainder of this section, and can be found in full version in the pages platform-guidelines and db-guidelines respectively

Platform Guidelines - Bignami Version

The Platform Guidelines contain the software and programming language requirements, coding conventions, and directions for development. This section contains only the most important points.

Please check the full version of this document at platform-guidelines if you want to know more details, if you have some doubt or if what you were looking for is not mentioned in this summary.

  • Programming Language is Java, in its latest or second to last version.
  • The source code must be documented according to the Javadoc style guide and tags.
  • Java components of can be developed as libraries, standalone applications, or server applications running in Apache Tomcat.
  • The source code is built nightly; build configuration should be provided in either Ant or Maven (preferred), Makefile, or shell script.
  • Third party libraries can be used, provided they are established, FOSS-licenced, and do not overlap functionalities. This applies also to third party libraries used in application developed in other languages.
  • Front-end applications can be deployed in Javascript, version EC 2015, and must support modern browsers.
  • Node.js can be used to deploy headless or server applications.
  • Web front ends use the latest HTML and CSS versions, must work on mobile devices (responsive design) and should implement some basic accessibility principle.
  • JSON must be used as exchange language, while XML is welcomed as well.
  • The latest or second to last version Apache Tomcat is used to run server application; only API/REST end points have direct access to the database server.
  • There's no file system persistence, everything must be stored in the DB. JDBC data source and passwords should be stored in environmental variables.
  • Pay attention to RAM usage, applications will undergo load testing.
  • PostgreSQL is used, but not in its recent release (expect to use 2-3 versions before the latest), PostGIS spatial extension is required as well.
  • Developers will have an unprivileged role to access the DB and must follow best practices to query the DB from Java/Javascript.

Database Guidelines - Bignami Version

The Database Guidelines contain the database design and database programming principles along with software version requirements. This section contains only the most important points.

Please check the full version of this document at db-guidelines if you want to know more details, if you have some doubt or if what you were looking for is not mentioned in this summary.

  • The database can be designed with one of the Relational Model, Object-Relational Mapping (ORM), or Semi-structured Data methodologies.
  • A database designed with either methodology must be shipped with - schema files containing the CREATE statements.
  • Each database must include a version table and indices on tables.
  • All (SQL) source code must be well-documented, with in-line comments and higher level documentation.
  • Use standard database features - Sequences, primary and foreign keys, constraints (unique, check, not null), default values, views, and so on and so forth.
  • Separate business logic from database design; avoid stored procedure as much as possible.
  • Small procedures and functions, if needed. must be written in PL/PgSQL.
  • Do not use foreign data wrappers.
  • Consider using declarative partitioning for large tables - and contact team beforehand to discuss it.
  • Always use UTF8 character encoding and do not override it.
  • Default collation is en_US, which works well for German and Italian as well.
  • Never use money type, but numeric.
  • Dates and time stamps must be store to avoid ambiguity. Never store them as text, but rather use their data types, date (in UTC format) and timestamp with timezone. Unix timestamp is accepted as well.
  • When using or manipulating JSON data always follow ISO_8601 standard.