Vision document for code.praqma.com

[adamhenriques]

This issue used to state our vision on how to organize CoDe pipelines and documentation for our software development; Praqma as well as Josra, Internal as well as public

Doctrines

• All individually releasable components, utilities or products shall be documented within the repository it self, directly on the integration branch.
• Documentation shall be published automatically as part of the pipeline.
• Each repository shall have it's own pipeline.
• Pipelines should be configurable based on pipeline types.
• Jenkins slaves should be minimalistic, and utilize container for tools and utilities

Documentation

The docs directory

Each component has a directory in the root named docs which contains a jekyll site that builds into the official documentation (end user reference manual).

The GitHub pages - deployment method

The master Jekyll site of the Praqma organization on GitHub is praqma/praqma.githuib.io. The Jekyll implementation of this repo is on the master branch and the CNAME file contains code.praqma.com

The DNS setting of code.praqma.com is a CNAME record pointing to praqma.github.io

Consequently the home of the documentation for our components resides is http://code.praqma.com

The individual repositories which shall be included in the documentation setup will have to publish their jekyll site on the gh-pages banch and CNAME file shall be unset or unpresent. This will default the site to be published as a subfolder to the site defined by the master repository, and the subfolders name will be the same as the git repository's name.

The implementation/version of Jekyll that we use is defined by the offical gh-pages ruby gem installed

gem install | update gh-pages

The styles

All styles shall be defined in the master repository (praqma/praqma.github.io) using SCSS.

The Jekyll sites in the component repositories shall use the CSS hosted by the master repository

All java scripts that are utilized shall also be contained in the master repository.

The JavaDoc

Components that contain JavaDoc shall publish the generated HTML to the gh-pagesbranch in the ´praqma/javadoc´ repo in a folde that has the same name as the git repository.

The ´praqma/javadoc´ shall be published on http://javadoc.praqma.com.

The branches

For repositories that are used to develop code, the master branch shall be considered the integration branch (the release train)..

For repositories used solely for Jeyll sites, the gh-pages branch shall be the integration branch

A new commit to the integration branch shall trigger a run in the repository's pipeline.

The integration to the integration branch shall be done by Jenkins (code.praqma.net/ci) utilizing the pretested integration plugin.

For code component, the repository root of gh-pages branch shall be a mirror of the docs folder on master using a subtree command.

Example:

> git subtree split -q --prefix docs master
13e153a1d6be094a68cc21a4bc8408eaac8d4d40
> git checkout gh-pages
> git merge 13e153a1d6be094a68cc21a4bc8408eaac8d4d40

The pipelines

All pipelines shall be maintained as configuration (JobDSL). An implementation shall exist for all the following Pipeline types:

The GiJeli pipelines

Toll-gate (pretested)

• `jekyll build``

Pipeline

• Link checker
• Scan for unused ressource
• Regression test (Geb)

Jenkins Ci Plugins

Toll-gate (pretested)

• Build and unit test.

Pipeline

• ...
• ...
• Regression test
• Merge docs on master to the root of gh-pages.
• Build and and publish embedded JavaDoc to Praqma/javadoc/<repo-name> on gh-pages branch

PAC

Toll-gate (pretested)

• Unit test.

Pipeline

• ...
• ...
• Regression test
• Merge docs on master to the root of gh-pages.
• ...

The containers

The Jenkins slaves should be as minimalistic. As many tools as possible should be utilized from docker container.

The Docker containers should be version controlled and tagged so that dependencies are managed.

[lakruzz]

I'm taking over #1 - I want the first issue to be the vision statement!