Skip to content

Commit

Permalink
Add ADR-0004 (#5202)
Browse files Browse the repository at this point in the history
- also update MADR to 2.1.2
- also fix external-libraries.txt
  • Loading branch information
koppor authored and Siedlerchr committed Aug 23, 2019
1 parent ee01d51 commit b8c3800
Show file tree
Hide file tree
Showing 5 changed files with 52 additions and 14 deletions.
13 changes: 7 additions & 6 deletions docs/adr/0000-use-markdown-architectural-decision-records.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,19 +7,20 @@ Which format and structure should these records follow?

## Considered Options

* [MADR](https://adr.github.io/madr/) 2.0.3 - The Markdown Architectural Decision Records
* [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) - The first incarnation of the term "ADR"
* [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) - The Y-Statements
* [MADR](https://adr.github.io/madr/) 2.1.2 – The Markdown Architectural Decision Records
* [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) The first incarnation of the term "ADR"
* [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) The Y-Statements
* Other templates listed at <https://github.com/joelparkerhenderson/architecture_decision_record>
* Formless - No conventions for file format and structure
* Formless No conventions for file format and structure

## Decision Outcome

Chosen option: "MADR 2.0.3", because
Chosen option: "MADR 2.1.2", because

* Implicit assumptions should be made explicit.
Design documentation is important to enable people understanding the decisions later on.
See also [A rational design process: How and why to fake it](https://doi.org/10.1109/TSE.1986.6312940).
* The MADR format is lean and fits our development style.
* The MADR structure is comprehensible and facilitates usage & maintenance.
* The MADR project is vivid.
* Version 2.0.3 is the latest one available when starting to document ADRs.
* Version 2.1.2 is the latest one available when starting to document ADRs.
34 changes: 34 additions & 0 deletions docs/adr/0004-use-mariadb-connector.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# Use MariaDB Connector

## Context and Problem Statement

JabRef needs to connect to a MySQL database.
See [Shared SQL Database](https://help.jabref.org/en/SQLDatabase) for more information.

## Considered Options

* Use MariaDB Connector
* Use MySQL Connector

Other alternatives are listed at <https://stackoverflow.com/a/31312280/873282>.

## Decision Outcome

Chosen option: "Use MariaDB Connector", because comes out best (see below).

## Pros and Cons of the Options

### Use MariaDB Connector

The [MariaDB Connector](https://mariadb.com/kb/en/library/about-mariadb-connector-j/) is a LGPL-licensed JDBC driver to connect to MySQL and MariaDB.

* Good, because can be used as drop-in replacement for MySQL connectopr

### Use MySQL Connector

The [MySQL Connector](https://www.mysql.com/de/products/connector/) is distributed by Oracle and licensed under GPL-2. Source: <https://downloads.mysql.com/docs/licenses/connector-j-8.0-gpl-en.pdf>.
Oracle added the [Universal FOSS Exception, Version 1.0](https://oss.oracle.com/licenses/universal-foss-exception/) to it, which seems to limit the effects of GPL.
More information on the FOSS Exception are available at <https://www.mysql.com/de/about/legal/licensing/foss-exception/>.

* Good, because it stems from the same development team than MySQL
* Bad, because the "Universal FOSS Exception" makes licensing more complicated.
1 change: 1 addition & 0 deletions docs/adr/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ This log lists the architectural decisions for JabRef.
- [ADR-0001](0001-use-crowdin-for-translations.md) - Use Crowdin for translations
- [ADR-0002](0002-use-slf4j-for-logging.md) - Use slf4j together with log4j2 for logging
- [ADR-0003](0003-use-gradle-as-build-tool.md) - Use Gradle as build tool
- [ADR-0004](0004-use-mariadb-connector.md) - Use MariaDB Connector

<!-- adrlogstop -->

Expand Down
8 changes: 5 additions & 3 deletions docs/adr/template.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# [short title of solved problem and solution]

* Status: [accepted | superseeded by [ADR-0005](0005-example.md) | deprecated | …] <!-- optional -->
* Status: [proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005](0005-example.md)] <!-- optional -->
* Deciders: [list everyone involved in the decision] <!-- optional -->
* Date: [YYYY-MM-DD when the decision was last updated] <!-- optional -->

Expand All @@ -27,11 +27,13 @@ Technical Story: [description | ticket/issue URL] <!-- optional -->

Chosen option: "[option 1]", because [justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force force | … | comes out best (see below)].

Positive Consequences: <!-- optional -->
### Positive Consequences <!-- optional -->

* [e.g., improvement of quality attribute satisfaction, follow-up decisions required, …]
*

Negative consequences: <!-- optional -->
### Negative Consequences <!-- optional -->

* [e.g., compromising quality attribute, follow-up decisions required, …]
*

Expand Down
10 changes: 5 additions & 5 deletions external-libraries.txt
Original file line number Diff line number Diff line change
Expand Up @@ -110,11 +110,6 @@ Project: java-diff-utils
URL: https://github.com/java-diff-utils/java-diff-utils
License: Apache-1.1

Id: mysql:mysql-connector-java
Project: MySQL Connector/J
URL: http://www.mysql.de/downloads/connector/j/
License: GPL-2.0 and Oracle's FOSS License Exception (http://www.mysql.com/about/legal/licensing/foss-exception/) allowing GPLv3

Id: net.java.dev.glazedlists:glazedlists_java15
Project: Glazed Lists
URL: http://www.glazedlists.com/
Expand Down Expand Up @@ -195,6 +190,11 @@ Project: jsoup
URL: https://github.com/jhy/jsoup/
License: MIT

Id: org.mariadb.jdbc:mariadb-java-client
Project: MariaDB Java Client
URL: https://mariadb.com/kb/en/library/about-mariadb-connector-j/
License: LGPL-2.1-or-later

Id: org.openoffice:juh
Project: OpenOffice.org
URL: http://www.openoffice.org/api/SDK
Expand Down

0 comments on commit b8c3800

Please sign in to comment.