Skip to content

Commit 7cea2d8

Browse files
PhilippSalvisbergPhilippSalvisberg
authored
Merge pull request #10 from PhilippSalvisberg/feature/issue_1
Feature/issue 1
2 parents bf590b3 + 3e1c63f commit 7cea2d8

File tree

171 files changed

+5843
-3
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

171 files changed

+5843
-3
lines changed

‎.gitignore

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# macOS internals
2+
.DS_Store
3+
4+
# NPM-related
5+
/node_modules
6+
/npm-debug.log*
7+
8+
# Files generated by build
9+
/build
10+
/material/manifest.json
11+
/MANIFEST
12+
/site
13+
/pdf
14+
15+
# Distribution files
16+
/dist
17+
/mkdocs_material.egg-info
18+
19+
# temporary files
20+
~$SQL-and-SQL-Coding-Guidelines.doc

‎PLSQL-and-SQL-Coding-Guidelines.doc

-4.88 MB
Binary file not shown.

‎PLSQL-and-SQL-Coding-Guidelines.pdf

-410 KB
Binary file not shown.

‎README.md

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,21 @@
22

33
## Introduction
44

5-
Trivadis published their guidelines for PL/SQL & SQL in 2009 in the context of the DOAG conference in Nuremberg. Since then these guidelines - written in Microsoft Word - have been continuously extended and improved. We think it is time to make these guidelines more adaptable for the individual #SmartDB application needs and to simplify the continous improvement of these guidelines.
5+
Trivadis published their guidelines for PL/SQL & SQL in 2009 in the context of the DOAG conference in Nuremberg. Since then these guidelines have been continuously extended and improved. Now they are managed as a set of markdown files. This makes the the guidelines more adaptable for individual application needs and simplifies the continous improvement.
66

7-
The next step will be to convert the existing guidelines to a set of Markdown files and use Jekyll to generate the guidelines as static HTML files or PDF.
7+
## HTML format
8+
9+
HTML is the primary output format. [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) is used to generate static HTML files and [Mike](https://github.com/jimporter/mike) to publish version specific variants. The following sites are available:
10+
11+
Link | Content
12+
-------------------------------------------------------------------- | -------
13+
<https://trivadis.github.io/plsql-and-sql-coding-guidelines/> | Latest Release
14+
<https://trivadis.github.io/plsql-and-sql-coding-guidelines/master/> | Current version based on the master branch, typically a snapshot version of the coming release
15+
<https://trivadis.github.io/plsql-and-sql-coding-guidelines/v3.3/> | Released version 3.3
16+
17+
## PDF format
18+
19+
PDF is the secondary output format. [wkhtmltopdf](https://wkhtmltopdf.org/) is used to generate the [PLSQL-and-SQL-Coding-Guidelines.pdf](https://raw.githubusercontent.com/Trivadis/plsql-and-sql-coding-guidelines/master/PLSQL-and-SQL-Coding-Guidelines.pdf).
820

921
## Releases
1022

@@ -30,4 +42,4 @@ Please file your bug reports, enhancement requests, questions and other support
3042

3143
## License
3244

33-
The Trivadis PL/SQL & SQL Coding Guidelines is licensed under the Apache License, Version 2.0. You may obtain a copy of the License at <http://www.apache.org/licenses/LICENSE-2.0>.
45+
The Trivadis PL/SQL & SQL Coding Guidelines are licensed under the Apache License, Version 2.0. You may obtain a copy of the License at <http://www.apache.org/licenses/LICENSE-2.0>.

‎custom-theme/main.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{% extends "base.html" %}

‎custom-theme/partials/header.html

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
<header class="md-header" data-md-component="header">
2+
<nav class="md-header-nav md-grid">
3+
<div class="md-flex">
4+
<div class="md-flex__cell md-flex__cell--shrink">
5+
<a href="{{ config.site_url | default(nav.homepage.url, true) }}" title="{{ config.site_name }}" class="md-header-nav__button md-logo">
6+
{% if config.theme.logo.icon %}
7+
<i class="md-icon">{{ config.theme.logo.icon }}</i>
8+
{% elif config.theme.logo.startswith("http") %}
9+
<img src="{{ config.theme.logo }}" height="30">
10+
{% else %}
11+
<img src="{{ base_url }}/{{ config.theme.logo }}" height="30">
12+
{% endif %}
13+
</a>
14+
</div>
15+
<div class="md-flex__cell md-flex__cell--shrink">
16+
<label class="md-icon md-icon--menu md-header-nav__button" for="__drawer"></label>
17+
</div>
18+
<div class="md-flex__cell md-flex__cell--stretch">
19+
<div class="md-flex__ellipsis md-header-nav__title" data-md-component="title">
20+
{% block site_name %}
21+
{% if config.site_name == page.title %}
22+
{{ config.site_name }} Version {{ config.extra.guideline_version }}
23+
{% else %}
24+
<span class="md-header-nav__topic">
25+
{{ config.site_name }} Version {{ config.extra.guideline_version }}
26+
</span>
27+
<span class="md-header-nav__topic">
28+
{{ page.title }}
29+
</span>
30+
{% endif %}
31+
{% endblock %}
32+
</div>
33+
</div>
34+
<div class="md-flex__cell md-flex__cell--shrink">
35+
{% block search_box %}
36+
{% if "search" in config["plugins"] %}
37+
<label class="md-icon md-icon--search md-header-nav__button" for="__search"></label>
38+
{% include "partials/search.html" %}
39+
{% endif %}
40+
{% endblock %}
41+
</div>
42+
{% if config.repo_url %}
43+
<div class="md-flex__cell md-flex__cell--shrink">
44+
<div class="md-header-nav__source">
45+
{% include "partials/source.html" %}
46+
</div>
47+
</div>
48+
{% endif %}
49+
</div>
50+
</nav>
51+
</header>

‎docker/Dockerfile

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
FROM centos:7.5.1804
2+
3+
LABEL maintainer="[email protected]"
4+
LABEL description="Tools to generate HTML and PDF using Materials for MkDocs and wkhtmltopdf."
5+
LABEL build.command="docker build . --tag trivadis/mktools:latest"
6+
7+
RUN yum install -y https://centos7.iuscommunity.org/ius-release.rpm
8+
RUN yum update -y
9+
RUN yum install -y python36u python36u-libs python36u-devel python36u-pip
10+
RUN yum install -y git
11+
RUN yum install -y wget
12+
13+
# Install wkhtmltox 0.12.4 since 0.12.5 cannot create TOCs, see https://github.com/wkhtmltopdf/wkhtmltopdf/issues/3995
14+
# RUN yum install -y https://github.com/wkhtmltopdf/wkhtmltopdf/releases/download/0.12.5/wkhtmltox-0.12.5-1.centos7.x86_64.rpm
15+
RUN yum install -y yum install -y wkhtmltopdf
16+
RUN wget -q https://github.com/wkhtmltopdf/wkhtmltopdf/releases/download/0.12.4/wkhtmltox-0.12.4_linux-generic-amd64.tar.xz -O /tmp/wkhtmltox.tar.xz && \
17+
tar xvf /tmp/wkhtmltox.tar.xz -C /tmp && \
18+
cp -rp /tmp/wkhtmltox/* /usr/local && \
19+
rm -rf /tmp/wkhtmltox*
20+
21+
RUN pip3.6 install --upgrade pip
22+
RUN pip3.6 install mkdocs \
23+
mkdocs-material \
24+
mkdocs-awesome-pages-plugin \
25+
pymdown-extensions \
26+
mike
27+
28+
ENV LC_ALL=en_US.utf8
29+
ENV LANG=en_US.utf8
30+
31+
# volume for GitHub project's root folder containing docs folder
32+
RUN mkdir /data
33+
VOLUME ["/data"]
34+
35+
# port for mkdocs serve
36+
EXPOSE 8000

‎docs/1-introduction/.pages

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
collapse_single_pages: true

‎docs/1-introduction/introduction.md

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# Introduction
2+
3+
This document describes rules and recommendations for developing applications using the PL/SQL & SQL Language.
4+
5+
## Scope
6+
7+
This document applies to the PL/SQL and SQL language as used within ORACLE databases and tools, which access ORACLE databases.
8+
9+
## Document Conventions
10+
11+
SQALE (Software Quality Assessment based on Lifecycle Expectations) is a method to support the evaluation of a software application source code. It is a generic method, independent of the language and source code analysis tools.
12+
13+
### SQALE characteristics and subcharacteristics
14+
15+
Characteristic | Description and Subcharacteristics
16+
-------------- | ----------------------------------
17+
Changeability | The capability of the software product to enable a specified modification to be implemented.<ul><li>Architecture related changeability</li><li>Logic related changeability</li><li>Data related changeability</li><ul>
18+
Efficiency | The capability of the software product to provide appropriate performance, relative to the amount of resources used, under stated conditions.<ul><li>Memory use</li><li>Processor use</li><li>Network use</li></ul>
19+
Maintainability | The capability of the software product to be modified. Modifications may include corrections, improvements or adaptation of the software to changes in environment, and in requirements and functional specifications.<ul><li>Understandability</li><li>Readability</li></ul>
20+
Portability | The capability of the software product to be transferred from one environment to another.<ul><li>Compiler related portability</li><li>Hardware related portability</li><li>Language related portability</li><li>OS related portability</li><li>Software related portability</li><li>Time zone related portability.</li></ul>
21+
Reliability | The capability of the software product to maintain a specified level of performance when used under specified conditions.<ul><li>Architecture related reliability</li><li>Data related reliability</li><li>Exception handling</li><li>Fault tolerance</li><li>Instruction related reliability</li><li>Logic related reliability</li><li>Resource related reliability</li><li>Synchronization related reliability</li><li>Unit tests coverage.</li></ul>
22+
Reusability | The capability of the software product to be reused within the development process.<ul><li>Modularity</li><li>Transportability.</li></ul>
23+
Security | The capability of the software product to protect information and data so that unauthorized persons or systems cannot read or modify them and authorized persons or systems are not denied access to them.<ul><li>API abuse</li><li>Errors (e.g. leaving a system in a vulnerable state)</li><li>Input validatation and representation</li><li>Security features.</li></ul>
24+
Testability | The capability of the software product to enable modified software to be validated.<ul><li>Integration level testability</li><li>Unit level testability.</li></ul>
25+
26+
### Severity of the rule
27+
28+
!!! bug "Blocker"
29+
Will or may result in a bug.
30+
31+
!!! danger "Critical"
32+
Will have a high/direct impact on the maintenance cost.
33+
34+
!!! warning "Major"
35+
Will have a medium/potential impact on the maintenance cost.
36+
37+
!!! tip "Minor"
38+
Will have a low impact on the maintenance cost.
39+
40+
!!! info "Info"
41+
Very low impact; it is just a remediation cost report.
42+
43+
### Keywords used
44+
45+
Keyword | Meaning
46+
----------- | -------
47+
Always | Emphasizes this rule must be enforced.
48+
Never | Emphasizes this action must not happen.
49+
Avoid | Emphasizes that the action should be prevented, but some exceptions may exist.
50+
Try | Emphasizes that the rule should be attempted whenever possible and appropriate.
51+
Example | Precedes text used to illustrate a rule or a recommendation.
52+
Reason | Explains the thoughts and purpose behind a rule or a recommendation.
53+
Restriction | Describes the circumstances to be fulfilled to make use of a rule.
54+
55+
### Why are standards important
56+
57+
For a machine executing a program, code formatting is of no importance. However, for the human eye, well-formatted code is much easier to read. Modern tools can help to implement format and coding rules.
58+
59+
Implementing formatting and coding standards has the following advantages for PL/SQL development:
60+
61+
* Well-formatted code is easier to read, analyze and maintain (not only for the author but also for other developers).
62+
* The developers do not have to define their own guidelines - it is already defined.
63+
* The code has a structure that makes it easier to avoid making errors.
64+
* The code is more efficient concerning performance and organization of the whole application.
65+
* The code is more modular and thus easier to use for other applications.
66+
67+
This document only defines possible standards. These standards are not written in stone, but are meant as guidelines. If standards already exist, and they are different from those in this document, it makes no sense to change them.
68+

‎docs/2-naming-conventions/.pages

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
collapse_single_pages: true

0 commit comments

Comments
 (0)