Coding standards

This file defines web development standarts for DRMAX.

Recommendations according to this standart:
"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" dle https://tools.ietf.org/html/rfc2119

BS4 browsers support:
https://getbootstrap.com/docs/4.0/getting-started/browsers-devices/

➟ Directory structure

This chapter describes the basic rules for naming files in a directory structure, recommends procedures, and specifies a directory structure for a standard web development project.

↓ Naming conventions #

The naming of each file or directory in your system must be according to the following rules. The reason for this is the compatibility between different operating systems and their versions. MUST

» Allowed characters

The allowed file-naming characters are: MUST

  • small characters of basic alphabet without any diacritics,
  • in justified cases -> large characters of the basic alphabet without any diacritics (for example, components, objects and classes),
  • digits (0 to 9),
  • only in justified cases -> hyphen/em-dash (not en-dash, nor nonbreaking hyphen) (for example source file classes)
  • underscore

These are the only symbols that you can use for file-naming.

Correct examples:

  • _card-list.scss
  • coding_standards_v01.docx
  • 20171231_vyrocni_zprava.docx

Wrong examples:

  • kódovací-standardy.docx
  • coding standards.docx
  • CodingStandardsV01.docs
  • Coding_Standards_V01.docs
  • 2018-01-01_vyrocni-zprava.docx
  • 2018-01-01_vyrocni_zprava.docx

» File extensions

Except for a few special exceptions, files must have their correct extension, which corresponds to its structure (MIME type). The file extension is always written in lowercase. MUST

Correct examples:

  • picture-with-people.jpg
  • coding-standards.docx

Wrong examples:

  • picture.JPG
  • picture_one.JPG
  • picture_one.jpg
  • coding-standards.DOCX

Files without extensions are typically environment configuration files. Those files are subject to their own naming and structural conventions according to their use. For example: webconfing, .git, etc.


» Date in a filename

When a date is used in a name of a file, it is always formatted in order of year, then month and day, and without any hyphens. The reason for this is to maintain the correct sorting right from the file system level and further. The date is always at the beginning of the file name.MUST

Correct examples:

  • 20180101_vyrocni_zprava.docx

Wrong examples:

  • Výroční zpráva 1.1.2018.docx
  • 18-1-1_vyrocni-zprava.docx
  • vyrocni-zprava_180101.docx
  • 2018-01-01_vyrocni-zprava.docx
  • 2017-24-12_Vánoční přání.docx

» Filename length

Some of the operating systems have a limited filename length along with the length of the absolute file path. Therefore, the path length along with the filename must not exceed 260 characters. MUST


↓ Web development projects #

Web development projects term stands for any project that will be available to users via any web browser in one of their environments. The directory structure of these projects must be set properly according to the following rules. SHOULD

» Non-public sources

Non-public sources term stands for any of the files and folders that are not directly accessible through any URL without passing through application logic. To prevent unauthorized access, these sources must be located outside the root of the site (DocumentRoot), ie. the directory to which the Internet domain is directed. Non-public sources are typically application source files, internal documents, and configuration files MUST


» Public sources = DocumentRoot

Public sources term stands for any files and folders provided to site visitors to view or download. Those files and folders are located inside the root directory of the site. Such sources are typically needed for correct page rendering (e.g., cascading styles known as CSS, JavaScript, images, fonts), downloads, and static HTML pages. MUST


» GIT directory structure:

  • src – source codes
  • build – re-compiled source code (do not use /dist)
  • etc – configuration files (for some applications, apache/nginx such as http.conf, … )
  • debian - for debian packag
  • service - for daemontools scripts (application run)
  • bin - scripts
  • www - document root apache/nginxe
  • test/postman - api texts/strings for postman
  • test/selenium - selenium tests
  • test/unit - unit tests

» GIT directory structure example:

  • /www/<PROJECTGROUP></<PROJECTNAME> application root (it is not a root vps/server)
    • app [755] – application directory
    • etc - configuration scripts (e.g. http.conf for apache/nginx)
    • log [775] - logs
      • http - logs for apache/nginx
    • vendor | node_modules [755] - third-party libraries directory (according to used technology)
    • www [755] – the root of the site, the domain is directed here
      • assets/css [775] - cascading style sheets (CSS) directory
      • assets/js [755] – JavaScript directory
      • assets/img [755] - images
      • assets/favicon [755] - favicons
      • assets/font[755] - fonts
      • data/upload [775] - a directory for uploading files through the application
    • README.md [644] – a file containing textual information about the project
    • composer.json [644] – configuration file
    • Makefile.app – a file containing info of ‚How to recompile the application?‘
  • React
    • app – main directory
      • components – presentation components (show content only)
      • containers - components containing status or receiving data from the site
      • store - redux store, action, reducers
      • utils - helpers
    • www - assets which will be added to the built-in application

➟ Third-party libraries

The usage of third-party libraries is permitted and recommended only if you’ll obey certain rules. It is important to verify the source from which the library comes, and to verify that the library does not contain unwanted or unsafe functionality such as sending important information to potential attackers. Only libraries licensed for such usage should be used. MUST

TODO: How will we be validating them? How will we be checking for new versions?


↓ Integration into the project #

All third-party libraries are used as they are and are no longer modified in the application. Interference with library source code is not allowed. Libraries have to be uploaded to the project only via NPM (https://www.npmjs.com/). MUST

In any scenario, where an intervence with third-party library is necessary, it is highly recommended to rather copy its whole content and paste it straight into the project. From that point this potential library is not considered as a third-party library anymore. NOT RECOMMENDED


↓ Creating a new internal library #

If a new internal library is created, the code must meet the following parameters:

  • Purity and validity of its code, MUST
  • Separately functional package (HTML, CSS cascading style sheets and JavaScript), SHOULD
  • Complete Documentation including definition of inputs, outputs and links to external or any other internal libraries SHOULD
  • Approval of the internal authority of the company MUST

Once such library is approved, it‘s is placed within the internal repository for potential usage.


→ Bower (we will not use it)


→ Optimization for browsers

This is a set of HTML code rules that helps to maintain good app rankings in search engines.


→ HTML code creation rules

This chapter defines the rules for creating and generating the final HTML code, which is later sent to any browsers for displaying.


↓ Standard #

The HTML 5.2 https://www.w3.org/TR/html52/ is the standard used in the HTML code part of web applications. At the beginning of each page, it is necessary to create a so-called doctype by using the following tag:

<!DOCTYPE html> MUST


↓ Naming conventions #

All individual HTML elements are always indicated by lowercase letters. RECOMMENDED

Correct examples:

  • <table>
  • <p>

Wrong examples:

  • <Table>
  • <TABLE>

Names of any element attributes are always in lowercase. RECOMMENDED

Correct examples:

  • <img src=”/image.jpg” alt=”image 1” title=”image 1”>
  • <td colspan=”2” data-sortable=”false”>

Wrong examples:

  • <td colSpan=”2”>
  • <span data-myFancyAttribute=”1”>
  • <td COLSPAN=”2”>

Names of any class and identifier are always compiled of lowercase letters of the elementary alphabet, hyphen, and underscore.

Correct examples:

  • order--submit-buton
  • submit-button

Wrong examples:

  • orderButton
  • tlačítko-objednávka

↓ Validity #

The whole code must be „well formed“ and „valid“ – without any errors or warnings. That means it must also comply with the rules of correct structure from the technical point of view (crossing of elements, closing of open elements) and also from the point of view of semantics (correct sequence, block elements are not included in non-block). SHOULD

Correct examples:

  • <table><tbody><tr><td>1</td><td>2</td></tr></tbody></table>
  • <p>

Wrong examples:

  • <ul><li>Lorem<li>Ipsum<li>Dolor</ul>
  • <strong><a href=”/link”>Lorem ipsum</strong></a>
  • <img><strong>Lorem ipsum</strong></img>/li>
  • <a><div>Lorem ipsum</div></a>

All elements, with some exceptions, must always have an opening and closing element. Joining is not allowed. The exceptions are <input>, <link>, <br>, <hr>, and <img>. Those are elements which do not have any enclosing parts. MUST

Correct examples:

  • <p>Lorem</p><p></p><p>ipsum</p>
  • <p>Lorem ipsum<br>dolor sit amet</p>
  • <img src=”image.jpg” alt=”image”>

Wrong examples:

  • <p>Lorem</p><p /><p>ipsum</p>
  • <img src=”image.jpg” alt=”image”></img>
  • <img src=”image.jpg” alt=”image” />

The final HTML code can be validated on the link https://validator.w3.org/ Some individual exceptions to ignore some of the rules can be negotiated in justified cases. For example the need to ignore the unauthorized namespace “xmlns: og“ which is required when linking to Facebook.

» Meta-information/metadata

Each page must contain the following information:

  • a standard declaration at the beginning of a document <!DOCTYPE html>, MUST
  • a correct title in the header between the tags <title>Page title</title>, which is not used repeatedly within other pages SHOULD
  • correct language settings on the html tag, for example <html lang=”cs”>....</html>, SHOULD
  • meta keywords OPTIONAL and meta description SHOULD , which are changed according to a page
  • the header contains information about favicon in the recommended formats MUST
    • for android devices any png is in the dimensions of 192x192 pixels
    • for apple devices any png is in the dimensions of 180x180, 152x152, 144x144, 120x120, 114x114, 76x76, 72x72, 60x60, 57x57
    • for normal browsers any png is in the dimensions of 16x16, 32x32, 96x96
    • manifest with links to icons

» Headings structure

Each page must always contain one <h1> heading which content corresponds to the content of a page (it’s not static). Headings must be used properly and according to a tree structure without skipping any of the levels. MUST

Correct examples:

  • h1
    • h2
    • h2
      • h3
      • h3
    • h2

Wrong examples:

  • h1
    • h2
      • h4
    • h3
      • h4
      • h5

Headings are never separated at the lowest level in the element tree

Correct examples:

  • <li><h2>Lorem ipsum></h2><p>Dolor sit amet</p></li>

Wrong examples:

  • <li><h2>Lorem ipsum</h2></li>

» Semantic elements

Elements must be used correctly for their purpose and must have the correct attributes:

  • images must always have set an attribute of alt =”...” MUST a title=”...” OPTIONAL
  • Tables can be used only for data displaying, and can’t be used to create any application design MUST
  • <em> and <strong> (instead of non-semantic <i> and <b>) tags are used to highlight a text SHOULD
  • links must have set the attribute of title=”...” OPTIONAL
  • non-site links must have set an attribute rel=”nofollow” OPTIONAL

» Social sites

The applications should have completed basic attributes for social networks according to the documentation available at http://ogp.me/ SHOULD The mostly supported social media platforms are Facebook and Twitter.

The list of these attributes is below:

  • og:site_name
  • og:type
  • og:locale
  • og:title
  • og:description
  • og:url
  • og:image (jpg image in dimensions of 1200x630px)
  • twitter:title
  • twitter:description

» Robots.txt

The robots.txt file is located in the root directory where the domain is located. MUST This file contains a declaration of whether crawling and indexing is enabled on the site. It also includes a declaration and a path to the project sitemap. Also, it can contain declarations and disabling access of robots for example to an administration. Cascading style sheets (CSS) and JavaScripts are not disabled. You can find examples and further documentation at: http://www.robotstxt.org/

Example of robots.txt file content:

User-agent: *
Disallow:
Crawl-delay: 30
sitemap: sitemaps.xml


» Sitemap.xml

The sitemap.xml file is located in the site root directory. MUST This file typically contains only links to other sitemaps that already have specific content. The syntax and examples can be found and https://www.sitemaps.org/

Each declaration is valid by syntax, and the <lastmod> tag always and exclusively contains the date of creation of the page, not the date when the sitemap has been generated. If the site/project is focused on graphical content/resources, it is recommended to create an image sitemap.

TODO: add split to parts, such as categories, products, etc. Add lastupdate tag


↓ Microdata #

Any site that display specific resources (such as a specific articles) should have MicroData listed. Microdata is embedded in HTML as elements and attributes. You can find the schema list is at http://schema.org/. The validity of the scheme can be verified on the online validator Available at https://search.google.com/structured-data/testing-tool?hl=cs

All product pages must contain Google Rich Snippets microdata to correctly show structured snippets such as price, manufacturer, ranking, vendor, and so on in the Google search results. More info about product microdata and implementation can be found at https://developers.google.com/search/docs/data-types/product the correctness of the implementation can be verified by https://search.google.com/structured-data/testing-tool/ MUST

Example of microdata implementation in HTML code:


↓ Semantic identifiers #

For a purpose of other tools, it is strongly recommended to add unique identifiers to elements which have an important functional impact. For example, we add a “button-complete-order“ ID to the order completion button for an online store (eshop). The rules for creating identifiers should meet the html rules mentioned in this documentation. Thanks to this we will be able to very comfortably do things like for example:

  • Add a conversion tracking with Google Tag Manager,
  • Create a Selenium test which will be able to complete the order or
  • Create a satisfaction questionnaire.

➟ Cascading style sheets

To create an application design – we use CSS 2.1 https://www.w3.org/TR/2011/REC-CSS2-20110607/
standard for cascading style sheets which support media queries. MUST

↓ General rules #

All cascading styles are stored in separate files outside the template, hence no inline styles are allowed. The only exceptions are when some parts of the design are dynamically generated (for example, background images ie the background-image css attribute). It is not allowed to overuse styles by using the !important declaration.


↓ Naming conventions #

All cascading styles must be written in lowercase letters with dashes and without any diacritics. IDs must not be used as CSS selectors because they should be reserved for automatic application testing. MUST

Correct examples:

  • .my-class-for-first-cell
  • .header-cell

Wrong examples:

  • .myClass
  • .MYCLASS
  • .my-class_first
  • #small-image
  • .moje-třída

Each CSS rule/attribute must be specified on its own line with and ended by semicolon. MUST

Zero-numeric values are set without any unit. SHOULD

Text values of any attribute are always placed within quotation marks. SHOULD

Correct examples:

  • font-size: 12px;
  • font-family: “Arial”;
  • padding-bottom: 0;

Wrong examples:

  • text-decoration: UNDERLINE;
  • padding-bottom: 0px;
  • font-size: 12px !important;

↓ SASS #

SASS is a library that brings known options from programming languages to the classic CSS. The CSS itself extends the possibility of using "variables", "expressions" and "mixins". In addition, in SASS, individual scripts can be nested in multiple levels (creating tree notation), which can reduce the amount of a written code. Basic mathematical operations can be used as well.

Unfortunately, the web browsers cannot process this code directly, so it is necessary to recompile it to pure CSS. The basic information about using the SASS preprocessor is available on the page http://sass-lang.com/guide.

When writing and modifying Bootstrap components – we have to use SCSS syntax (with parentheses). The ways of how to install the SASS preprocessor are listed on the page http://sass-lang.com/install.

» Variables

Variables can be used as constants with a fixed value or can be combined with each other. The name of the variable always starts with a dollar sign, followed by a name using the same rules as for pure CSS (using lowercase letters, dashes, without diacritics). After the name there must be a colon, then a value and finally a semicolon. MUST

Correct examples:

  • $nice-blue: #5b83ad;
  • .header { color: $nice-blue; }

Wrong examples:

  • $niceBlue: #5b83ad;
  • .header { color: $niceBlue; }

Variables must be used especially in the following cases:

  • Color definitions,
  • Defenitions of a size of letters,
  • Font-family definitions
  • Definition of a bootstrap container size (see below).

Correct examples:

  • $color-red: #ff0000; .red { color:$color-red; }; .error { border-color: $color-red; }

Wrong examples:

  • .red { color: #ff0000; }; .error { border-color: #ff0000; }

If there is a publicly available SASS source (URL) then for global variable definitions across the company for encoding is required to import this internal resource and use variables from this source. The SASS global definition reference should always be a part of the assignment.


» Mixins

The term of ‚mixin‘ can be understood as using a macro with a parameter (or without a parameter), which makes it easier to write browser prefixes for new CSS properties.

Example:

@mixin border-radius($radius) {
-webkit-border-radius: $radius;
-moz-border-radius: $radius;
-ms-border-radius: $radius;
border-radius: $radius; }

.box { @include border-radius(10px); }


» Compilation

To compile SASS files, we use the https://gruntjs.com/ grunt file, which you can install using the npm (node.js package manager) through the console:

$ npm install -g grunt-cli RECOMMENDED


» Structure

To make the source code easier to use, separate SASS and compiled CSS into separate directories and files according to their meaning MUST , so for example.:

  • web projects:
    • src/sass
      • admin.scss – administration styling files
      • includes.scss - used to import the third-party libraries (bootstrap, jquery,…)
      • reset.scss - basic settings of the HTML elements
      • variables.scss - basic settings of the environment variables
      • mixins.scss – basic macros
      • styles.scss – custom styles for the application
    • assets/cs
      • styles.min.css
      • admin.min.css
      • reset.min.css

Therefore, it is possible to write custom styles to any file - typically styles.scss. At the beginning, only the includes.scss file is imported to ensure that all variables and libraries will be loaded correctly.

It is good to divide styles into scss files by context.

File naming suggestions:

  • forms.scss – form elements rules
  • slider.scss, tabs.scss - extra widgets rules
  • typography.scss - rules for basic elements such as headings, bullets, or tables

» Third party resources import

Third-party libraries are imported right at the start of processing other SASS files so later they can be overloaded in subsequent SASS files. This is because it‘s not allowed to directly interfere with third-party scripts. RECOMMENDED

SASS import example:


↓ Bootstrap #

Bootstrap (https://getbootstrap.com/) is a simple and free downloadable set of tools for web applications and for web development. It contains HTML & CSS-based design templates for typography, forms, buttons, navigation, and other interface components as well as other optional JavaScript extensions. It also supports responsive design since version 2.0. This means that the page layout is dynamically adapted according to the used device (desktop PC, tablet, mobile phone). We should use Bootstrap 4 in a stable version to create front-end components https://github.com/twbs/bootstrap/releases/tag/v4.0.0 MUST

Bootstrap is available with several JavaScript components in the form of jQuery plug-ins:

  • Modal (modal dialogs / layovers),
  • Dropdown (drop-down-menu boxes)
  • Scrollspy (the heading pointer to which the page is currently moved),
  • Tab (switchable elements from which only one is displayed at the same time),
  • Tooltip (a pop-up bubble help window),
  • Pop-over (pop-up windows),
  • Alert (warning or informative boxes),
  • Button (buttons),
  • Collapse (effect which shrinks the content of the element),
  • Carousel ("Image switcher")
  • Typeahead (a whisperer).

PS: Any use of the jQuery must be approved by drmax authority.

» Bootstrap usage

It is necessary to import basic CSS and JS library into each HTML project where Bootstrap is planned to be included/used (include JS only when using jQuery):


» Responsivity by using a bootstrap

To create responsive websites, you can effectively use the Bootstrap Grid library, which brings a set of CSS classes that are designed for a fast responsive use. 12 columns are used by default. MUST

  • Lines must be placed inside .container or .container-fluid to properly align and indent any elements
  • Use rows to create groups of horizontal columns.
  • The HTML content itself should be placed inside columns that are direct descendants of rows.
  • Predefined CSS classes for a grid like .row and .col-xs-4 are available for a quick layout creation. They can also be used for a more semantic layout.
  • Columns have borders (spaces between the columns content) defined by padding. Therefore, a negative line shift is used for the first and last columns.
  • he columns grid is composed of 12 columns which can be used. For example, we use the .col-xs-4 class for 3 columns of the same width.
  • If more than 12 columns are used in a row, the entire group of extra columns will be wrapped into a new row.
  • Grid definition classes depending on the screen width are limited as "greater or equal" to the set breakpoint and will overwrite the classes to be used for smaller screen resolutions.
  • Variables for media queries eg. @screen-sm-min, @screen-xs-max, @screen-md-min and so on.

Column classes names set according to a resolution later determine for which resolution we define how many grid points the column should hold.

We do not use bootstrap styles naming in explicit way so there will be no .col-sx-12 anywhere in the HTML code.

Examples:

  • .col-xs-12 = a full width on very small devices
  • .col-sm-6 = half of the width on small devices
  • .col-md-4 = one-third of the width on medium-sized facilities
  • .col-lg-3 = quarter of the width on large devices

↓ Rules for output #

During the conversion of SASS to CSS a minification can be used. In the production mode the use is mandatory. It is recommended to minify via grunt file when compiling source SASS and JS files. RECOMMENDED

So the application will always be linked to eg styles.min.css not styles.css

TODO: Add minification tools


↓ Graphic sources format #

Graphic resources/sources means all files used to display images and design documents in a web browser.


↓ Icons #

Icons are graphic materials used/placed in controls. Icons can be displayed in one of two ways below:

  1. as SVG. RECOMMENDED
  2. as a generated font displaying icons directly in vectors. For this you can use available libraries like bootstrap or FontAwesome http://fontawesome.io/

↓ Images #

Other images are in a format appropriate for the image type. For transparent images we should use only the PNG format. All images in this format are optimized by the service of TinyPNG
https://tinypng.com/ RECOMMENDED

To display photos we should use only the JPG format saved as progressive JPG
(gradually sharpening). MUST

» CDN

CDN is not required for any projects unless it‘s specified in the specification. In this case, the application is described in detail in the project documentation. In particular, projects which are robust or solely focused on graphical resources are particularly useful. RECOMMENDED

Use https://www.cloudflare.com/

➟ JavaScript

It is an interpreted scripting language used on websites to control various interactive GUIs, create advanced animations, input front-end validation of form data, and other functions associated with many of the user inputs.

↓ Version #

Only ECMAScript 5 is used for backward compatibility for browser viewing. It is not prohibited to save source code as ECMAScript 6 and use compilers (eg Babel) to translate it to a previous version that you need to send to the users.

Psat v ECMAScript 5


↓ Quality assurance #

To check the quality assurance of the JavaScript code use JShint. MUST
Do not use jslint.


↓ Naming convetions #

» Variables and functions names

All names of the variables and functions in JavaScript must be according to the so-called "camelCase" syntax, where the first letter is always small and each additional word is capitalized instead of using a space. The use of diacritics, dashes and underscores is not allowed. Variable names are written in English but comments can be in a different language.

Correct examples:

  • var firstVariable = “variable”;
  • function secondFunctionForTest(testParam) {}

Wrong examples:

  • var first-variable = “variable”;
  • var první proměnná = “variable”;
  • var prvni_Promenna = “variable”;

There is always a space behind operators (= + - * /) and commas.
The code block indentation is made up of 4 spaces.


» General rules

  • Each individual function block must end with a semicolon.
  • The opening brace for the functions is located on the first line and there still have to be an extra space in front of it.
  • The closing brace for the functions is placed on a separate line and there is no extra space in front of it.
  • There is no semicolon behind this last brace.
  • Code lines should not exceed 80 characters if you cannot avoid a shortcutted text, you need to divide the line into another one – preferably separated by an operator or comma

» Rules for objects

  • The opening brace is on the first line after the object name and there is an extra space in front of it.
  • Properties and their values are separated by a colon followed by a space.
  • Text values are quoted, numeric values not.
  • The comma at the end of the line is not listed after the last property value.
  • The closing brace for functions is placed on a separate line and there is no extra space in front of it.
  • There is a semicolon behind this last brace.

↓ Comments #

JavaScript comments must be stored in JavaDoc MUST ,

See more at https://en.wikipedia.org/wiki/Javadoc and they are mandatory for all public functions and libraries.

Example:

/**
* Constructs a table drag object.
*
* Provides the ability to drag to manipulate a table and its fields.
*
* @constructor
* @param {HTMLTableElement} table DOM object for the table to be made draggable.
* @param {object} tableSettings Settings for the table.
*/

We use Doxyxgen to generate a documentation, see more at www.doxygen.org


↓ Third-party scripts usage rules #

Similar as with the use of third-party CSS, third-party JavaScript libraries are not allowed to modify their content as well.

To speed up site loading, no third-party libraries should be imported into sites where they are not used.

➟ Output check and code cleanliness


↓ Validity #

The output of the final website must meet the calidity of a HTML and CSS code according to W3C validator https://validator.w3.org/ JavaScript must be without any errors.


↓ Code analysis #

Automatic code check should be done using the online service of Codacy MUST


↓ Browser version #

All web applications must be debugged for the following browser versions:

  • Internet Explorer (version 11.0 a newer) + EDGE
  • Firefox (at least two major versions after the current version at the date of application deployment) see more at https://www.mozilla.org/en-US/firefox/releases/
  • Safari on MacOS (at least two major versions after the current version at the date of application deployment)
  • Chrome (at least two major versions after the current version at the date of application deployment) see more here

These rules can be adjusted to the current application requirements.

➟ Versioning system

The GIT repository is not the subject of this document.

↓ Naming versions #

Each version name has the following notation (accroding to https://semver.org/) MUST

X.Y.Z optionally X.Y.Z-AAA ( major.minor.patch )

  • X - major version, increases when adding features which are not backward compatible
  • Y - minor version, increases when adding features which are backward compatible
  • Z - patch version (sometimes named as build), increases error corrections, ie merges, hotfixes which are backward compatible
  • AAA - release note, eg alpha, beta, rc (release candidate), r (release). This note only makes sense when debugging packages for deployment, making pre-release packages, and so on.

Correct examples:

  • v1.0.0
  • v1.2.3-alpha
  • v3.0.0

↓ CHANGELOG.md #

The CHANGELOG.md file is generated automatically based on the GIT commit that follows the rules of keepachangelog.com/en/1.0.0/. This file is usually located at the root of the project and contains a list of versions with a short commentary of what has been changed, what has been added and what has been deleted in each version. Below the generic header which contains the file formatting rules - the version is located with the date when it was created, and with a list of changes below. The content of the file is formatted by MarkDown. Detailed description can be found on

http://keepachangelog.com/en/1.0.0/
Example of file content CHANGELOG.md:

# Changelog
All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html)

## [0.0.3] - 2014-08-09
### Added
- Better explanation of the difference between the file ("CHANGELOG") and its function "the change log".

### Changed
- Refer to a "change log" instead of a "CHANGELOG" throughout the site to differentiate between the file and the purpose of the file — the logging of changes.

### Removed
- Remove empty sections from CHANGELOG, they occupy too much space and create too much noise in the file. People will have to assume that the missing sections were intentionally left out because they contained no notable changes.

## [0.0.2] - 2014-07-10
### Added
- Explanation of the recommended reverse chronological release ordering.

## [0.0.1] - 2014-05-31
### Added
- project created, base structure