Terminology

YDA

YDA is the abbreviation of Yamato Daiwa Automation, the name of this tool about documentation which. Here, the Yamato Daiwa is the name of of Japanese startup, currently specializing on custom web development, and also on development of the libraries, frameworks and other tools (including YDA).

Project

In the programming context, the project — is the files and folders set which are required for the development of specific digital project (web site, web application, console application, native application, library etc.) and has the common parent directory. The YDA utility is intended exactly for the working with projects, not with individual files.

Project build(ing)

In the "project building", the gerund "building" refers mainly on the process, namely the forming of the output files based on the source files. This process is the main thing which YDA doing.

The "build" could be the noun or verb.

As noun, the "build" in the "project build" means all output files of the project. Usually, they are been outputted to the common directory called "build directory", but YDA has no such limitation.
As verb, the "build" in the build project means the various processes forming the output files such as source code compiling, images optimization etc.

Not all technologies assumes the project building. For example, if the web site or web application has been written by pure HTML, CSS and PHP (the last one is interpreted programming language what means that source code files are being executed directly without compilation to the output executable files), in this case it is nothing to build. About YDA, it has being developed for the working with Pug, Stylus и TypeScript languages each of them intended to be transpiled to the output code (HTML, CSS and JavaScript respectively). Besides, output images files could differ with source ones because of automated optimization. In the case, when the files are not required any processing, the plain copying could be setup to not mix the source files and output ones.

Scenario

In the project building context, the task is the specialized work for the computer among project building automation. Currently the following primary tasks on which YDA is specializing could be highlighted.

The processing of the markup with source code on Pug, the preprocessor language
The processing of the styles with source code on Stylus, the preprocessor language
The processing of ECMAScript logic with source code on TypeScript language. Although this language rarely called by "preprocessor language", it will be so until it's runtimes will become popular. The transpiling to both browser JavaScript and Node.js is available.
Images processing
The copying of fronts, videos, audios and ony other files
Automatic opening of the browser on complete of initial project building with automatic reloading of browser page on updating of output code
Automatic starting of Node.js server on complete of initial project building with automatic restarting of this server on updating of output code

Task

In the context of YDA, and also Gulp, and similar project bulling tools, the scenario are the tasks been arranged into sequences (series) and parallels.

The correct tasks arranging is critical for both correct executing and performance optimization. For example, the markup processing is been executed only when files all other files types are ready to correctly resolve the paths to styles, images etc., and browser open automatically last of all, when the markup is ready.

Because the YDA is more high-level tool than Gulp, the users does not need to care about correct arranging of the tasks to series and parallels, it is enough to know which scenarios are available.

Currently, YDA suggests 2 following scenarios:

Project Incremental Building: First, the full project building is being executed, then on changing of the source files, the selective rebuilding will be. This way, the application will be executed until will not be manually stopped or the critical error occur. If required, the automatic browser opening (if the project has the client part) and/or automatic starting of the local server (if the project has the Node.js server part) could be setup.
Production-like Project Building: The project is being built completely, then the application will finish. The functionality like automatic reloading of the browser page is unavailable in this scenario because of its purpose.

Project Building Mode

Both scenarios could be executed in the multiple project building modes, each of them has the features. YDA is suggesting 5 following project building modes. In the case of development of web site or the GUI application, this modes also could be considered as the stages, but not the stages of development of the product as a whole — they are the stages of the development of a separate page or a specific functionality.

Incremental

Actual for the incremental project building scenario. According to this scenario, first full project building will be executed, then with the changes of the source code, the selective rebuilding will be executed. For all incremental modes, from the project building tools it is required to provide good performance optimization. Also, in the case of the development of the websites and GUI applications, it is required the automated browser page reloading and other measures provides the comfortable product development with high quality feedback including the early notifications about various problems such as HTML code validity violations.

Static Preview: Designed and the development stage on which the engineer completely focused on the markup and styles, while the JavaScript dynamics and server part (backend) is the matter of subsequent stages. Thus, this project building mode is actual only for the development of the websites and the GUI applications. The significand requirement to project building system on current development state is the providing of the browsing of the output files by the customers or managers without technical knowledge and specialized software such as npm or git, herewith the images and other multimedia files must currently displaying in browser. Simply put, the "open downloaded HTML file in browser — and everything displaying" principe must be respected.
Local Development: In the case of websites or GUI applications, on this stage, unlike the previous one, the full-fledged implementation of the JavaScript dynamics of the client path and also the server part (backend) is being executed. On this stage, the project building tool must provide the optimized project rebuilding, automated reloading of the browser page, automated restarting of the local server on the changing of the files if there is the Node.js server part.

Production-like

It is usual before the publishing of the web site or the web application they being launched on the test server with the limited access to make testers able to check the bugs which has not been detected on previous development stages. On the stages of this group, there is no the automated project rebuilding or automated browser reloading on updating of files anymore because built web site or web application intended to be launched on the remote server, # [+Keyword--YDID not] on the local machine. Although such builds must be close to the final one (the production one, that is why the modes of this group is being called "production-like"), some features (for example, the logging level or the dataset) could be different dependent on the specific mode.

Testing: Unlike the local development mode, the testers, managers and other people related with target web site or web application has access to the instance built in this mode. As it obvious from the name, the primary target of the current stage is the testing for the detecting of the bugs.
Staging: In large projects, besides the testing version, there is the similar one called "staging". The difference are usually not large: it tends to be the usage of the data close with the real one, not the data designed for testing purposes. Thanks to it, the management and customers feels like using the final published instance of the web site or web application. By the way, because this, it better to preset the staging build to customers, not the testing one.
Production: The website or web application built in this more are intended to be published for the target audience. In comparison with previous modes, in this one the strictest security settings are required, and the data must be managed with caution because the accidental change or deleting of some data could entail the losses of various scale. Also, on this stage, the developers are tending to minimize the output to the browser console.

Entry Points and Children files

The entry point is the name of design pattern, in the general case it is the file, function or class method from which the program execution started. In the context of the certain technology, it could have more specific meaning.

The majority of the programming languages and preprocessors supports the splitting of the source file to arbitrary number of constituents. Here, the parent files and children files must be distinguished. Because the children files also could be spit to constituents, the thee-like hierarchical structure is being formed, where is the entry point is topmost element.

The children files is frequently being called "partial files", while originally "partial" does not imply the vertical hierarchy. Because this vertical hierarchy matters for the YDA, the "child file" / "children files" terms has been selected.

By Files Type

Markup

In markup case, the entry point is the file corresponding to complete HTML document.

If the entry point does not have the children files, the valid HTML document must be the result of Pug-to-HTML conversation. And if there are the children files, they are must not be converted to HTML separately, because this way the valid HTML document will not be at the output.

The regular HTML file could not be split to multiple files, but the HTML pre-processors including Pug allows to do it on the source code stage. In YDA working with Pug preprocessor, the "entry point" term is being applied to both source Pug files and output HTML files. To include the children file to the entry point or another children file, include directive is being used. The extends directive also means the usage of children file, because the file on which target one being extended in not mandatory represents the complete HTML document.

Not every Pug file could be the entry point, while any HTML file is the entry point.