Skip to content
This repository was archived by the owner on Apr 21, 2026. It is now read-only.

Commit 04b6839

Browse files
author
dpatanin
committed
re-add adr
1 parent 3cc29d9 commit 04b6839

3 files changed

Lines changed: 130 additions & 0 deletions

File tree

‎adr/adr_0000.adoc‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
[[ADR-0000]]
2+
= ADR-0000: Short present tense imperative phrase, less than 50 characters, like a email subject
3+
4+
[cols="h,d",grid=rows,frame=none,stripes=none,caption="Status",%autowidth]
5+
|====
6+
// Use one of the ADR status parameter based on status
7+
// Please add a cross reference link to the new ADR on 'superseded' ADR.
8+
// e.g.: {adr_suposed_by} <<ADR-0000>>
9+
| Status
10+
| PROPOSED | ACCEPTED | REJECTED | DEPRECATED | SUPOSED_BY <<ADR-0000>>
11+
12+
| Date
13+
| YYYY-MM-DD
14+
15+
| Author(s)
16+
| John Doe <john.doe@snafu.com> +
17+
jane Doe <jane.doe@snafu.com>
18+
// ...
19+
|====
20+
21+
== Context
22+
23+
<What is the issue that we're seeing that is motivating this decision or change.>
24+
25+
== Decision
26+
27+
<What is the change that we're actually proposing or doing.>
28+
29+
== Consequences
30+
31+
<What becomes easier or more difficult to do because of this change.>

‎adr/adr_0001.adoc‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
[[ADR-0001]]
2+
= ADR-0001: Choosing the framework for the new secureCodeBox Website
3+
4+
[cols="h,d",grid=rows,frame=none,stripes=none,caption="Status",%autowidth]
5+
|====
6+
// Use one of the ADR status parameter based on status
7+
// Please add a cross reference link to the new ADR on 'superseded' ADR.
8+
// e.g.: {adr_suposed_by} <<ADR-0000>>
9+
| Status
10+
| ACCEPTED
11+
12+
| Date
13+
| 2019-08-21
14+
15+
| Author(s)
16+
| Daniel Patanin daniel.patanin@iteratec.com,
17+
Jannick Hollenbach jannick.hollenbach@iteratec.com
18+
// ...
19+
|====
20+
21+
== Context
22+
23+
There are tons of different frameworks for building websites out there. We must choose the most fitting one for our use, fulfilling our mandatory requirements:
24+
25+
• Common programming language, if applicable easy to learn
26+
• Overall easy to use and start-up, also locally
27+
• Tutorials, examples and a good documentation
28+
• Bonus points for great and many easy to use templates and plugins
29+
• Needs continuous support and contribution
30+
• Must be able to be deployed as GitHub pages
31+
32+
We will choose from the following popular/trending:
33+
34+
https://gridsome.org/[Gridsome] +
35+
https://www.gatsbyjs.org/[Gatsby] +
36+
https://gohugo.io/[Hugo] +
37+
https://jekyllrb.com/[Jekyll]
38+
39+
=== Research
40+
41+
These frameworks do all fulfill the requirements to the extent that I estimate them as wellsuited. First, I researched the listed features on the respective sites or quickly googled after it
42+
specifically and found instantly the requested feature. I followed up with in general overview
43+
of how old the frameworks, how popular they are and for example pages build with them.
44+
Afterwards I searched for comparison blogs and posts, mostly to examine their comments.
45+
Most of these „pro-cons “-posts are inaccurate and very superficial, but luckily because of that
46+
the comment sections hold interesting discussions and comparisons from overall features and
47+
usability to specific issues and problems of each framework and which framework fits what
48+
use-cases in general. After this research I’ve come to a majority of similar experience sharing
49+
and discussions. These described the distribution of these frameworks as follows (roughly
50+
summarized):
51+
52+
Gridsome is like Gatsby just for VueJS.
53+
Gatsby is blazing fast after building the pages but requires a little bit more understanding of
54+
JavaScript and React and may not be as easy to get behind if you’ve never built a site with a
55+
static site generator before.
56+
Hugo is fast in building and based on Golang. But as a newbie to that language you’ll find yourself using the documentation very much, unless you learn this language to a curtain depth.
57+
Jekyll is simple in templating and very good for quickly starting a small blog site but based on
58+
ruby and therefore requires ruby dependencies.
59+
60+
== Decision
61+
62+
So, it seems that Hugo is a pretty good choice for sites with many, many…. like many pages.
63+
Jekyll seems to fit for a quick build. Gatsby and Gridsome require a bit more time to learn but
64+
have their advantages in speed and growth of the site. And whether you choose Gridsome over
65+
Gatsby relies on whether you want to use VueJS or not.
66+
67+
Finally we’ve decided to use Gatsby. Some of the main reasons is it’s fast performance, the extensive documentation and tutorials and also the language, since Hugo (the
68+
other framework we considered mainly) is based on Golang, and as for my part as a developer I
69+
feel completely comfortable and prefer working with JSX. Overall it comes down to preferences mostly, since we’re not going to build a giant Website, nor are we planning on implementing “crazy” Features.
70+
71+
== Consequences
72+
a
73+
For the integration of our multi-repository documentation we’ll use
74+
Antora if working this out with Gatsby is going to be more difficult than integrating Antora.
75+
We’re aware that using Gatsby requires a bit more maintenance and has the drawback, that if
76+
anybody else will maintain or work on the website, this person will need to at least understand
77+
the basics of React and GraphQL.

‎adr/adr_README.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Architecture Decision Records (ADRs)
2+
3+
This subdirectory contains all ADRs for the architecture documentation. The ids of these ADRs are within the number range from 0001 to 0999. The 0000 is reserved for the example templarte.
4+
5+
Architectural decisions are, where appropriate, documented with the ADR template from [Michael Nygard][nygard]. A template can be found at ```0000.adoc``` and [here][template]. We extend this template with the date when this decision was made.
6+
7+
Important key points from the blog of [Michael Nygard][nygard]:
8+
9+
> We will keep a collection of records for "architecturally significant" decisions: those that affect the structure, non-functional characteristics, dependencies, interfaces, or construction techniques.
10+
>
11+
> Each record describes a set of forces and a single decision in response to those forces. Note that the decision is the central piece here, so specific forces may appear in multiple ADRs.
12+
>
13+
> We will keep ADRs in the project repository under ```adr/NNNN.adoc```
14+
>
15+
> ADRs will be numbered sequentially and monotonically. **Numbers will not be reused.**
16+
>
17+
> If a decision is reversed, we will **keep the old** one around, but mark it as superseded. (It's still relevant to know that it was the decision, but is no longer the decision.)
18+
19+
Please take a look in the ADR template ```0000.adoc``` for more information about the internal structure.
20+
21+
[nygard]: http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions
22+
[template]: https://github.com/joelparkerhenderson/architecture_decision_record/blob/master/adr_template_by_michael_nygard.md

0 commit comments

Comments
 (0)