search

Praqma / praqma.github.io

The home of http://code.praqma.com. It's repo that will host documentation for all our development
1 stars 3 forks source link

Vision document for code.praqma.com #1

Open adamhenriques opened 8 years ago

adamhenriques commented 8 years ago

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

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)

Pipeline

Toll-gate (pretested)

Pipeline

Toll-gate (pretested)

Pipeline

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 commented 8 years ago

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