From 604428fa0b21e1e4e2b45d8488695ae6e0fd1ab6 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Wed, 25 Nov 2020 12:05:38 +0100 Subject: [PATCH 01/42] chore(docs): change link to fsf.org in licencse file --- LICENSE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/LICENSE.md b/LICENSE.md index 1110e89..4564b29 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -2,7 +2,7 @@ GNU General Public License ========================== _Version 3, 29 June 2007_ -_Copyright © 2007 Free Software Foundation, Inc. <>_ +_Copyright © 2007 [Free Software Foundation, Inc.](https://fsf.org)_ Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. -- GitLab From 00d4cd30c02ed00ca0cd1d464198a7d3fa9ae119 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Wed, 25 Nov 2020 12:07:26 +0100 Subject: [PATCH 02/42] docs: add first skeleton for pages --- docs/api/core/filter.md | 4 +++ docs/api/core/logging.md | 4 +++ docs/api/core/registered-systems.md | 4 +++ docs/api/core/ticket-assignee.md | 4 +++ docs/api/core/ticket-builder.md | 4 +++ docs/api/core/ticket-system-builder.md | 4 +++ docs/api/core/ticket-system.md | 4 +++ docs/api/core/ticket.md | 4 +++ docs/api/exceptions.md | 5 +++ docs/api/index.md | 6 ++++ docs/api/systems/gitlab/filter.md | 4 +++ docs/api/systems/gitlab/ticket-assignee.md | 4 +++ docs/api/systems/gitlab/ticket-builder.md | 4 +++ .../systems/gitlab/ticket-system-builder.md | 4 +++ docs/api/systems/gitlab/ticket-system.md | 4 +++ docs/api/systems/gitlab/ticket.md | 4 +++ docs/index.md | 6 ++++ docs/unified-ticketing/changelog-softlink.md | 1 + docs/unified-ticketing/contributing.md | 5 +++ docs/unified-ticketing/license-softlink.md | 1 + docs/unified-ticketing/usage.md | 5 +++ mkdocs.yml | 33 +++++++++++++++++-- 22 files changed, 115 insertions(+), 3 deletions(-) create mode 100644 docs/api/core/filter.md create mode 100644 docs/api/core/logging.md create mode 100644 docs/api/core/registered-systems.md create mode 100644 docs/api/core/ticket-assignee.md create mode 100644 docs/api/core/ticket-builder.md create mode 100644 docs/api/core/ticket-system-builder.md create mode 100644 docs/api/core/ticket-system.md create mode 100644 docs/api/core/ticket.md create mode 100644 docs/api/exceptions.md create mode 100644 docs/api/index.md create mode 100644 docs/api/systems/gitlab/filter.md create mode 100644 docs/api/systems/gitlab/ticket-assignee.md create mode 100644 docs/api/systems/gitlab/ticket-builder.md create mode 100644 docs/api/systems/gitlab/ticket-system-builder.md create mode 100644 docs/api/systems/gitlab/ticket-system.md create mode 100644 docs/api/systems/gitlab/ticket.md create mode 120000 docs/unified-ticketing/changelog-softlink.md create mode 100644 docs/unified-ticketing/contributing.md create mode 120000 docs/unified-ticketing/license-softlink.md create mode 100644 docs/unified-ticketing/usage.md diff --git a/docs/api/core/filter.md b/docs/api/core/filter.md new file mode 100644 index 0000000..e072a49 --- /dev/null +++ b/docs/api/core/filter.md @@ -0,0 +1,4 @@ +# Filter + +!!! todo + write usage api docs diff --git a/docs/api/core/logging.md b/docs/api/core/logging.md new file mode 100644 index 0000000..a2dcffd --- /dev/null +++ b/docs/api/core/logging.md @@ -0,0 +1,4 @@ +# Logging + +!!! todo + write usage api docs diff --git a/docs/api/core/registered-systems.md b/docs/api/core/registered-systems.md new file mode 100644 index 0000000..d12cd63 --- /dev/null +++ b/docs/api/core/registered-systems.md @@ -0,0 +1,4 @@ +# Registered Systems + +!!! todo + write usage api docs diff --git a/docs/api/core/ticket-assignee.md b/docs/api/core/ticket-assignee.md new file mode 100644 index 0000000..58c4449 --- /dev/null +++ b/docs/api/core/ticket-assignee.md @@ -0,0 +1,4 @@ +# Ticket Assignee + +!!! todo + write usage api docs diff --git a/docs/api/core/ticket-builder.md b/docs/api/core/ticket-builder.md new file mode 100644 index 0000000..f59c52a --- /dev/null +++ b/docs/api/core/ticket-builder.md @@ -0,0 +1,4 @@ +# Ticket-Builder + +!!! todo + write usage api docs diff --git a/docs/api/core/ticket-system-builder.md b/docs/api/core/ticket-system-builder.md new file mode 100644 index 0000000..a9c6743 --- /dev/null +++ b/docs/api/core/ticket-system-builder.md @@ -0,0 +1,4 @@ +# Ticketsystem-Builder + +!!! todo + write usage api docs diff --git a/docs/api/core/ticket-system.md b/docs/api/core/ticket-system.md new file mode 100644 index 0000000..3628c58 --- /dev/null +++ b/docs/api/core/ticket-system.md @@ -0,0 +1,4 @@ +# Ticketsystem + +!!! todo + write usage api docs diff --git a/docs/api/core/ticket.md b/docs/api/core/ticket.md new file mode 100644 index 0000000..94e7a54 --- /dev/null +++ b/docs/api/core/ticket.md @@ -0,0 +1,4 @@ +# Ticket + +!!! todo + write usage api docs diff --git a/docs/api/exceptions.md b/docs/api/exceptions.md new file mode 100644 index 0000000..097d94d --- /dev/null +++ b/docs/api/exceptions.md @@ -0,0 +1,5 @@ +# Exceptions + +!!! todo + - list exceptions available + - explain inheritance structure diff --git a/docs/api/index.md b/docs/api/index.md new file mode 100644 index 0000000..32aa137 --- /dev/null +++ b/docs/api/index.md @@ -0,0 +1,6 @@ +# Java-API + +!!! todo + - introductional text about library usage + - api docs structure explanation + - hint about no autogenerated JavaDoc, but manually written docs diff --git a/docs/api/systems/gitlab/filter.md b/docs/api/systems/gitlab/filter.md new file mode 100644 index 0000000..40c876b --- /dev/null +++ b/docs/api/systems/gitlab/filter.md @@ -0,0 +1,4 @@ +# Gitlab-Filter + +!!! todo + write usage api docs diff --git a/docs/api/systems/gitlab/ticket-assignee.md b/docs/api/systems/gitlab/ticket-assignee.md new file mode 100644 index 0000000..b35aa76 --- /dev/null +++ b/docs/api/systems/gitlab/ticket-assignee.md @@ -0,0 +1,4 @@ +# Gitlab-Ticket Assignee + +!!! todo + write usage api docs diff --git a/docs/api/systems/gitlab/ticket-builder.md b/docs/api/systems/gitlab/ticket-builder.md new file mode 100644 index 0000000..720dcde --- /dev/null +++ b/docs/api/systems/gitlab/ticket-builder.md @@ -0,0 +1,4 @@ +# Gitlab-Ticket-Builder + +!!! todo + write usage api docs diff --git a/docs/api/systems/gitlab/ticket-system-builder.md b/docs/api/systems/gitlab/ticket-system-builder.md new file mode 100644 index 0000000..28e1f0a --- /dev/null +++ b/docs/api/systems/gitlab/ticket-system-builder.md @@ -0,0 +1,4 @@ +# Gitlab-Ticketsystem-Builder + +!!! todo + write usage api docs diff --git a/docs/api/systems/gitlab/ticket-system.md b/docs/api/systems/gitlab/ticket-system.md new file mode 100644 index 0000000..7901ec3 --- /dev/null +++ b/docs/api/systems/gitlab/ticket-system.md @@ -0,0 +1,4 @@ +# Gitlab-Ticketsystem + +!!! todo + write usage api docs diff --git a/docs/api/systems/gitlab/ticket.md b/docs/api/systems/gitlab/ticket.md new file mode 100644 index 0000000..c8a2b00 --- /dev/null +++ b/docs/api/systems/gitlab/ticket.md @@ -0,0 +1,4 @@ +# Gitlab-Ticket + +!!! todo + write usage api docs diff --git a/docs/index.md b/docs/index.md index 8980264..6a54a61 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,9 @@ +[![pipeline state](https://transfer.hft-stuttgart.de/gitlab/9Lukas5/unified-ticketing/badges/master/pipeline.svg)](https://transfer.hft-stuttgart.de/gitlab/9Lukas5/unified-ticketing/pipelines) +[![License GPLv3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) +[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org) + # Unified Ticketing !!! Todo + - generally what this is about + - who's responsible for it diff --git a/docs/unified-ticketing/changelog-softlink.md b/docs/unified-ticketing/changelog-softlink.md new file mode 120000 index 0000000..699cc9e --- /dev/null +++ b/docs/unified-ticketing/changelog-softlink.md @@ -0,0 +1 @@ +../../CHANGELOG.md \ No newline at end of file diff --git a/docs/unified-ticketing/contributing.md b/docs/unified-ticketing/contributing.md new file mode 100644 index 0000000..9e5f0f6 --- /dev/null +++ b/docs/unified-ticketing/contributing.md @@ -0,0 +1,5 @@ +# Contributing + +!!! todo + - Write Basic stuff a contributor needs to full-fill & know + - link to the Developers Guide found in top-bar diff --git a/docs/unified-ticketing/license-softlink.md b/docs/unified-ticketing/license-softlink.md new file mode 120000 index 0000000..f0608a6 --- /dev/null +++ b/docs/unified-ticketing/license-softlink.md @@ -0,0 +1 @@ +../../LICENSE.md \ No newline at end of file diff --git a/docs/unified-ticketing/usage.md b/docs/unified-ticketing/usage.md new file mode 100644 index 0000000..18f6e40 --- /dev/null +++ b/docs/unified-ticketing/usage.md @@ -0,0 +1,5 @@ +# Usage + +!!! todo + - Write how to add dependency to pom + - Write what repo config in pom needed diff --git a/mkdocs.yml b/mkdocs.yml index 46a70d5..6cdbf1a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,17 +1,44 @@ -site_name: Unified Ticketing Doku +site_name: Unified Ticketing Docs -repo_name: 'Unified Ticketing Java Bibliothek' +repo_name: 'Code on Transfer Portal' repo_url: 'https://transfer.hft-stuttgart.de/gitlab/9Lukas5/unified-ticketing' edit_uri: 'blob/master/docs/' docs_dir: docs -copyright: 'Copyright © 2020 Hochschule für Technik Stuttgart' +copyright: 'Copyright © 2020 University for Applied Sciences Stuttgart' use_directory_urls: false nav: + - Index: 'index.md' - Home: - Index: 'index.md' + - Changelog: 'unified-ticketing/changelog-softlink.md' + - Usage: 'unified-ticketing/usage.md' + - Contributing: 'unified-ticketing/contributing.md' + - License: 'unified-ticketing/license-softlink.md' + - API: + - Index: 'api/index.md' + - Core: + - Filter: 'api/core/filter.md' + - Logging: 'api/core/logging.md' + - Registered Systems: 'api/core/registered-systems.md' + - Ticket: 'api/core/ticket.md' + - Ticket Assignee: 'api/core/ticket-assignee.md' + - Ticket Builder: 'api/core/ticket-builder.md' + - Ticketsystem: 'api/core/ticket-system.md' + - Ticketsystem Builder: 'api/core/ticket-system-builder.md' + - Exceptions: 'api/exceptions.md' + - Systems: + - GitLab: + - Filter: 'api/systems/gitlab/filter.md' + - Ticket: 'api/systems/gitlab/ticket.md' + - Ticket Assignee: 'api/systems/gitlab/ticket-assignee.md' + - Ticket Builder: 'api/systems/gitlab/ticket-builder.md' + - Ticketsystem: 'api/systems/gitlab/ticket-system.md' + - Ticketsystem Builder: 'api/systems/gitlab/ticket-system-builder.md' + - Developers Guide: + - Index: 'dummy.md' theme: name: 'material' -- GitLab From b21b04b5a925b5b176b785fb0ec6dc6e256d849e Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Wed, 25 Nov 2020 12:09:59 +0100 Subject: [PATCH 03/42] chore: add main contributing file linking to the pages one --- CONTRIBUTING.md | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..dcc23ec --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,2 @@ +Information on how to contribute to this project, is written in the docs. +See here: [docs/unified-ticketing/contributing.md](docs/unified-ticketing/contributing.md) -- GitLab From 2da6ff786ec11389304d34f68f7f24d8d572a161 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Wed, 25 Nov 2020 13:58:11 +0100 Subject: [PATCH 04/42] refactor(docs): add missing dev-guide to skeleton --- docs/developers-guide.md | 8 ++++++++ mkdocs.yml | 2 +- 2 files changed, 9 insertions(+), 1 deletion(-) create mode 100644 docs/developers-guide.md diff --git a/docs/developers-guide.md b/docs/developers-guide.md new file mode 100644 index 0000000..1dca947 --- /dev/null +++ b/docs/developers-guide.md @@ -0,0 +1,8 @@ +# Developers Guide + +!!! todo + - small styleguide per used language + - need for unittests + - where to put what kind of class(core/systems package) + - how to commit (conventional changelog) + - GitLab workflow diff --git a/mkdocs.yml b/mkdocs.yml index 6cdbf1a..66c52d8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -38,7 +38,7 @@ nav: - Ticketsystem: 'api/systems/gitlab/ticket-system.md' - Ticketsystem Builder: 'api/systems/gitlab/ticket-system-builder.md' - Developers Guide: - - Index: 'dummy.md' + - Index: 'developers-guide.md' theme: name: 'material' -- GitLab From 0744f0613035553ddb66d5c3246dc4ac3aa66742 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Wed, 25 Nov 2020 14:25:57 +0100 Subject: [PATCH 05/42] refactor(docs): index: make conventional commits badge orange --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 6a54a61..f7c8c43 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,6 @@ [![pipeline state](https://transfer.hft-stuttgart.de/gitlab/9Lukas5/unified-ticketing/badges/master/pipeline.svg)](https://transfer.hft-stuttgart.de/gitlab/9Lukas5/unified-ticketing/pipelines) [![License GPLv3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) -[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org) +[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-orange.svg)](https://conventionalcommits.org) # Unified Ticketing -- GitLab From 36633ce9a550838327a8d3e93e6f44b98757c358 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Wed, 25 Nov 2020 14:27:22 +0100 Subject: [PATCH 06/42] refactor(docs): index: add badge to point to latest tag version --- docs/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/index.md b/docs/index.md index f7c8c43..7a61b06 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,4 @@ +[![latest version](https://img.shields.io/badge/dynamic/json?color=green&label=latest%20release&query=%24%5B0%5D.name&url=https%3A%2F%2Ftransfer.hft-stuttgart.de%2Fgitlab%2Fapi%2Fv4%2Fprojects%2F154%2Frepository%2Ftags%3Fper_page%3D1)](https://transfer.hft-stuttgart.de/gitlab/9Lukas5/unified-ticketing/-/packages) [![pipeline state](https://transfer.hft-stuttgart.de/gitlab/9Lukas5/unified-ticketing/badges/master/pipeline.svg)](https://transfer.hft-stuttgart.de/gitlab/9Lukas5/unified-ticketing/pipelines) [![License GPLv3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-orange.svg)](https://conventionalcommits.org) -- GitLab From ffbfb5d22ceaf3150759f1d27ae86190090059a6 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Wed, 25 Nov 2020 14:28:02 +0100 Subject: [PATCH 07/42] refactor(docs): index: add badge to show latest pipeline state(all not master-only) --- docs/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/index.md b/docs/index.md index 7a61b06..937fc91 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,6 @@ [![latest version](https://img.shields.io/badge/dynamic/json?color=green&label=latest%20release&query=%24%5B0%5D.name&url=https%3A%2F%2Ftransfer.hft-stuttgart.de%2Fgitlab%2Fapi%2Fv4%2Fprojects%2F154%2Frepository%2Ftags%3Fper_page%3D1)](https://transfer.hft-stuttgart.de/gitlab/9Lukas5/unified-ticketing/-/packages) [![pipeline state](https://transfer.hft-stuttgart.de/gitlab/9Lukas5/unified-ticketing/badges/master/pipeline.svg)](https://transfer.hft-stuttgart.de/gitlab/9Lukas5/unified-ticketing/pipelines) +[![latest dev pipeline](https://img.shields.io/badge/dynamic/json?color=lightgrey&label=latest%20dev%20pipeline&query=%24%5B0%5D.status&url=https%3A%2F%2Ftransfer.hft-stuttgart.de%2Fgitlab%2Fapi%2Fv4%2F%2Fprojects%2F154%2Fpipelines%3Fper_page%3D1)](https://transfer.hft-stuttgart.de/gitlab/9Lukas5/unified-ticketing/-/packages) [![License GPLv3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-orange.svg)](https://conventionalcommits.org) -- GitLab From bf73c8ef0dedf43bbe19523a5d254a99cfe75e64 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Wed, 25 Nov 2020 15:11:49 +0100 Subject: [PATCH 08/42] refactor(docs): index: major restructure & begin of content - moving badge links to the bottom of file as reference - write first introducing text - add chapter captions and todos for them --- docs/index.md | 41 +++++++++++++++++++++++++++++++++-------- 1 file changed, 33 insertions(+), 8 deletions(-) diff --git a/docs/index.md b/docs/index.md index 937fc91..ecb740f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,11 +1,36 @@ -[![latest version](https://img.shields.io/badge/dynamic/json?color=green&label=latest%20release&query=%24%5B0%5D.name&url=https%3A%2F%2Ftransfer.hft-stuttgart.de%2Fgitlab%2Fapi%2Fv4%2Fprojects%2F154%2Frepository%2Ftags%3Fper_page%3D1)](https://transfer.hft-stuttgart.de/gitlab/9Lukas5/unified-ticketing/-/packages) -[![pipeline state](https://transfer.hft-stuttgart.de/gitlab/9Lukas5/unified-ticketing/badges/master/pipeline.svg)](https://transfer.hft-stuttgart.de/gitlab/9Lukas5/unified-ticketing/pipelines) -[![latest dev pipeline](https://img.shields.io/badge/dynamic/json?color=lightgrey&label=latest%20dev%20pipeline&query=%24%5B0%5D.status&url=https%3A%2F%2Ftransfer.hft-stuttgart.de%2Fgitlab%2Fapi%2Fv4%2F%2Fprojects%2F154%2Fpipelines%3Fper_page%3D1)](https://transfer.hft-stuttgart.de/gitlab/9Lukas5/unified-ticketing/-/packages) -[![License GPLv3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) -[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-orange.svg)](https://conventionalcommits.org) +[![latest version][badge-latest-tag]][project-packages] +[![pipeline state][badge-master-pipe]][project-pipelines] +[![latest dev pipeline][badge-latest-pipe]][project-pipelines] +[![License GPLv3][badge-gplv3]](https://www.gnu.org/licenses/gpl-3.0) +[![Conventional Commits][badge-conventional-commits]](https://conventionalcommits.org) # Unified Ticketing -!!! Todo - - generally what this is about - - who's responsible for it +This is the documentation for a Java-library called `unified-ticketing`. +This lib provides generic interfaces to interact with tickets +from different ticket systems out of your Java code. + +This library is a maven artifact, +published under the [GNU GPL-v3][gplv3] license. +The source code is publicly available from the [transfer portal][transferportal] of the [University of Applied Sciences Stuttgart][hfthome]. + +## What to find where + +!!! todo + explain how the documentation is structured + +## Maintainer + +!!! todo + Me/University + +[badge-conventional-commits]: https://img.shields.io/badge/Conventional%20Commits-1.0.0-orange.svg +[badge-gplv3]: https://img.shields.io/badge/License-GPLv3-blue.svg +[badge-latest-pipe]: https://img.shields.io/badge/dynamic/json?color=lightgrey&label=latest%20dev%20pipeline&query=%24%5B0%5D.status&url=https%3A%2F%2Ftransfer.hft-stuttgart.de%2Fgitlab%2Fapi%2Fv4%2F%2Fprojects%2F154%2Fpipelines%3Fper_page%3D1 +[badge-latest-tag]: https://img.shields.io/badge/dynamic/json?color=green&label=latest%20release&query=%24%5B0%5D.name&url=https%3A%2F%2Ftransfer.hft-stuttgart.de%2Fgitlab%2Fapi%2Fv4%2Fprojects%2F154%2Frepository%2Ftags%3Fper_page%3D1 +[badge-master-pipe]: https://transfer.hft-stuttgart.de/gitlab/9Lukas5/unified-ticketing/badges/master/pipeline.svg +[gplv3]: unified-ticketing/license-softlink.md +[hfthome]: https://www.hft-stuttgart.de +[project-packages]: https://transfer.hft-stuttgart.de/gitlab/9Lukas5/unified-ticketing/-/packages +[project-pipelines]: https://transfer.hft-stuttgart.de/gitlab/9Lukas5/unified-ticketing/pipelines +[transferportal]: https://transfer.hft-stuttgart.de -- GitLab From 04e0beeb319ec696dfd654171a9431f5bc94abc6 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Wed, 25 Nov 2020 16:09:46 +0100 Subject: [PATCH 09/42] refactor(docs): index: move all left badge links to file end --- docs/index.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index ecb740f..bf3e020 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,8 +1,8 @@ [![latest version][badge-latest-tag]][project-packages] [![pipeline state][badge-master-pipe]][project-pipelines] [![latest dev pipeline][badge-latest-pipe]][project-pipelines] -[![License GPLv3][badge-gplv3]](https://www.gnu.org/licenses/gpl-3.0) -[![Conventional Commits][badge-conventional-commits]](https://conventionalcommits.org) +[![License GPLv3][badge-gplv3]][gplv3] +[![Conventional Commits][badge-conventional-commits]][convcomm] # Unified Ticketing @@ -29,6 +29,7 @@ The source code is publicly available from the [transfer portal][transferportal] [badge-latest-pipe]: https://img.shields.io/badge/dynamic/json?color=lightgrey&label=latest%20dev%20pipeline&query=%24%5B0%5D.status&url=https%3A%2F%2Ftransfer.hft-stuttgart.de%2Fgitlab%2Fapi%2Fv4%2F%2Fprojects%2F154%2Fpipelines%3Fper_page%3D1 [badge-latest-tag]: https://img.shields.io/badge/dynamic/json?color=green&label=latest%20release&query=%24%5B0%5D.name&url=https%3A%2F%2Ftransfer.hft-stuttgart.de%2Fgitlab%2Fapi%2Fv4%2Fprojects%2F154%2Frepository%2Ftags%3Fper_page%3D1 [badge-master-pipe]: https://transfer.hft-stuttgart.de/gitlab/9Lukas5/unified-ticketing/badges/master/pipeline.svg +[convcomm]: https://conventionalcommits.org [gplv3]: unified-ticketing/license-softlink.md [hfthome]: https://www.hft-stuttgart.de [project-packages]: https://transfer.hft-stuttgart.de/gitlab/9Lukas5/unified-ticketing/-/packages -- GitLab From 9c0a27ed81b62a97b434d52619cc496d0c365f3f Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Wed, 25 Nov 2020 16:14:26 +0100 Subject: [PATCH 10/42] refactor(readme): add hint to docs root, in case pages are down --- README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/README.md b/README.md index a2df26a..bd0a2df 100644 --- a/README.md +++ b/README.md @@ -4,3 +4,8 @@ This is the repository of the unified-ticketing library. Documentation for this is done with GitLab Pages using MkDocs and is available here: https://transfer.hft-stuttgart.de/pages/unified-ticketing/ + +If you don't want to open the Webpage or it is not available for whatever reason, +the documentation root is in [docs/index.md][docs-root] + +[docs-root]: docs/index.md -- GitLab From 14563ba591c37a511ac25524074918ce5b6f0963 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Wed, 25 Nov 2020 16:34:29 +0100 Subject: [PATCH 11/42] refactor(docs): index: rename version badge to show 'maven' as label --- docs/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index bf3e020..5a8c8c4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,4 +1,4 @@ -[![latest version][badge-latest-tag]][project-packages] +[![maven][badge-latest-tag]][project-packages] [![pipeline state][badge-master-pipe]][project-pipelines] [![latest dev pipeline][badge-latest-pipe]][project-pipelines] [![License GPLv3][badge-gplv3]][gplv3] @@ -27,7 +27,7 @@ The source code is publicly available from the [transfer portal][transferportal] [badge-conventional-commits]: https://img.shields.io/badge/Conventional%20Commits-1.0.0-orange.svg [badge-gplv3]: https://img.shields.io/badge/License-GPLv3-blue.svg [badge-latest-pipe]: https://img.shields.io/badge/dynamic/json?color=lightgrey&label=latest%20dev%20pipeline&query=%24%5B0%5D.status&url=https%3A%2F%2Ftransfer.hft-stuttgart.de%2Fgitlab%2Fapi%2Fv4%2F%2Fprojects%2F154%2Fpipelines%3Fper_page%3D1 -[badge-latest-tag]: https://img.shields.io/badge/dynamic/json?color=green&label=latest%20release&query=%24%5B0%5D.name&url=https%3A%2F%2Ftransfer.hft-stuttgart.de%2Fgitlab%2Fapi%2Fv4%2Fprojects%2F154%2Frepository%2Ftags%3Fper_page%3D1 +[badge-latest-tag]: https://img.shields.io/badge/dynamic/json?color=green&label=maven&query=%24%5B0%5D.name&url=https%3A%2F%2Ftransfer.hft-stuttgart.de%2Fgitlab%2Fapi%2Fv4%2Fprojects%2F154%2Frepository%2Ftags%3Fper_page%3D1 [badge-master-pipe]: https://transfer.hft-stuttgart.de/gitlab/9Lukas5/unified-ticketing/badges/master/pipeline.svg [convcomm]: https://conventionalcommits.org [gplv3]: unified-ticketing/license-softlink.md -- GitLab From 74c7105e023dfa7572f71835682081d9c0024402 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Wed, 25 Nov 2020 16:52:30 +0100 Subject: [PATCH 12/42] chore(gitignore): add vscode project folder --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index 8a4c59a..795da40 100644 --- a/.gitignore +++ b/.gitignore @@ -12,6 +12,9 @@ env/ # Apple .DS_Store +# VSCode +.vscode/ + # NetBeans **/nbproject/private/ **/nbproject/Makefile-*.mk -- GitLab From b8d6d92693c03e12fdbae854235797020dd2363c Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Wed, 25 Nov 2020 16:53:11 +0100 Subject: [PATCH 13/42] refactor(docs): index: do 'what to find where' --- docs/index.md | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index 5a8c8c4..b88ebed 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,8 +16,31 @@ The source code is publicly available from the [transfer portal][transferportal] ## What to find where -!!! todo - explain how the documentation is structured +The documentation is split in three main parts, navigable on the top-bar. +Each main-part gives you a navigation of it's content on the left. +On the right, the currents page table of contents is shown. +The icon in the upper left brings you from anywhere back to this start-page. +In the upper right you can go to the source code repository of this library and documentation. +Leftwards a full-text search is provided. + +The part you are reading right now (__Home__), is the main website. +Following is a list, what each site contains: + + - __Changelog:__ auto-generated changelog from the commits + - __Contributing:__ + - Prerequisites to be able to be a contributor to this project + - Needed machine-setup to develop (both for the library and documentation part) + - __License:__ GNU GPLv3 content + - __Usage:__ + - needed entries to get this library into your own maven-project + - some code-snippets showing the libs capabilites + +The __API__ part holds a detailed description, for each publicly accessible class and their methods. +There is an own index file, explaining the package structure of the library +and how it is documented. + +The __Developers Guide__ is the part, you have to lookup the conventions and workflows used in this project, +if you decide to contribute to it. ## Maintainer -- GitLab From 1d96606b2f05d800e6acdd506c133d042c0e1fc5 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Wed, 25 Nov 2020 17:46:09 +0100 Subject: [PATCH 14/42] refactor(docs): index: do 'maintainer' --- docs/index.md | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index b88ebed..2a6ab79 100644 --- a/docs/index.md +++ b/docs/index.md @@ -44,9 +44,24 @@ if you decide to contribute to it. ## Maintainer -!!! todo - Me/University +This library and it's development belongs to the University of Applied Sciences Stuttgart. +It was originally developed as bachelors-thesis by Lukas Wiest +[e-mail][9l5-hft-mail] +[Twitter][9l5Twitter] +[GitHub][9l5GH] +[GitLab][9l5GL]. +The guardian professor was Prof. Dr. Gero Lueckemeyer +[e-mail][lueck-hft-mail] +[university profile][lueck-hft-profile] +[GitHub][lueck-GH] +[Xing][lueck-Xing]. +He is the current maintainer for this project and the appropriate contact for questions, access request, etc. + +[9l5-hft-mail]: mailto:62wilu1bif@hft-stuttgart.de +[9l5GH]: https://www.github.com/9Lukas5 +[9l5GL]: https://www.gitlab.com/9Lukas5 +[9l5Twitter]: https://twitter.com/9Lukas5 [badge-conventional-commits]: https://img.shields.io/badge/Conventional%20Commits-1.0.0-orange.svg [badge-gplv3]: https://img.shields.io/badge/License-GPLv3-blue.svg [badge-latest-pipe]: https://img.shields.io/badge/dynamic/json?color=lightgrey&label=latest%20dev%20pipeline&query=%24%5B0%5D.status&url=https%3A%2F%2Ftransfer.hft-stuttgart.de%2Fgitlab%2Fapi%2Fv4%2F%2Fprojects%2F154%2Fpipelines%3Fper_page%3D1 @@ -55,6 +70,10 @@ if you decide to contribute to it. [convcomm]: https://conventionalcommits.org [gplv3]: unified-ticketing/license-softlink.md [hfthome]: https://www.hft-stuttgart.de +[lueck-GH]: https://github.com/lueckemeyer +[lueck-hft-mail]: mailto:gero.lueckemeyer@hft-stuttgart.de +[lueck-hft-profile]: https://www.hft-stuttgart.de/p/gero-lueckemeyer +[lueck-Xing]: https://www.xing.com/profile/Gero_Lueckemeyer [project-packages]: https://transfer.hft-stuttgart.de/gitlab/9Lukas5/unified-ticketing/-/packages [project-pipelines]: https://transfer.hft-stuttgart.de/gitlab/9Lukas5/unified-ticketing/pipelines [transferportal]: https://transfer.hft-stuttgart.de -- GitLab From 086f8d0673af159194bd229a27ce68798b3d9248 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Thu, 26 Nov 2020 10:11:09 +0100 Subject: [PATCH 15/42] refactor(docs): home: write 'usage' --- docs/unified-ticketing/usage.md | 67 +++++++++++++++++++++++++++++++-- 1 file changed, 64 insertions(+), 3 deletions(-) diff --git a/docs/unified-ticketing/usage.md b/docs/unified-ticketing/usage.md index 18f6e40..a7c834d 100644 --- a/docs/unified-ticketing/usage.md +++ b/docs/unified-ticketing/usage.md @@ -1,5 +1,66 @@ # Usage -!!! todo - - Write how to add dependency to pom - - Write what repo config in pom needed +## Add as dependency in own project + +This library can be used as maven dependency in an own project. + +!!! attention + As it is not published to maven central, + but the GitLab integrated package registry, + you must configure an additional repository in your pom. + +__repository config:__ +```xml + + unified-ticketing + https://transfer.hft-stuttgart.de/gitlab/api/v4/projects/154/packages/maven + +``` + +__dependency information:__ +```xml + + de.hftstuttgart + unified-ticketing + 0.1.0 + +``` + +??? tip "example how your pom should look like" + ```xml + + + + + + de.hftstuttgart + unified-ticketing + 0.1.0 + + + + + + + gitlab-maven + https://transfer.hft-stuttgart.de/gitlab/api/v4/projects/154/packages/maven + + + + + ``` + +## Use in code + +There are two central classes: `TicketSystem` and `Ticket`. +The majority of the library is written with the fluent-api design pattern. + +To begin, you'll need an instance of `TicketSystem`. +This can be done, by calling the builder mechanism or pass a URI with all needed information. + +Using this `TicketSystem` object you can search for tickets in the connected space, +change and save them or create new tickets. + +To get full details of the available API, please switch to the [API docs](../api/index.md). +There you can find information and examples regarding the generic parts of the library, +as-well as system specific information, e.g. how an URI instantiation string has to look like, etc. -- GitLab From 6c5b18844a8764a8df58f5c837de94e4bae501d8 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Thu, 26 Nov 2020 10:14:59 +0100 Subject: [PATCH 16/42] refactor(docs): api: write 'index' --- docs/api/index.md | 68 ++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 64 insertions(+), 4 deletions(-) diff --git a/docs/api/index.md b/docs/api/index.md index 32aa137..463afc3 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -1,6 +1,66 @@ # Java-API -!!! todo - - introductional text about library usage - - api docs structure explanation - - hint about no autogenerated JavaDoc, but manually written docs +This is the API-Documentation, +holding detailed information for each publicly available action you can do with each class. +Below the structure of the library is explained and some generic examples are shown. +## library structure + +The library is structured into three packages: + +1. `de.hftstuttgart.unifiedticketing.core` +1. `de.hftstuttgart.unifiedticketing.exceptions` +1. `de.hftstuttgart.unifiedticketing.systems` + +The core package contains the classes defining the generic API, +to be implemented by each supported system. +The systems package contains a sub-package per supported system, +which then holds the implementations of the core classes. +The exceptions package has some own exception types, +used throughout the lib. + +For each package, this documentation provides a chapter in the navigation on the left. + +## examples + +!!! info + These examples are not specific to a certain system. + Therefore they can contain placeholders for system specific parts. + To get these parts, you'll have to go to the dedicated API-docs part. + +??? example "create TicketSystem instance" + __from builder:__ + ```java + TicketSystem ts = TicketSystem.fromBuilder() + . + .build(); + ``` + + __from uri:__ + ```java + TicketSystem ts = TicketSystem.fromUri(); + ``` + +??? example "searching tickets" + __without filters:__ + ```java + ts.find().get(); + ``` + + __only open tickets and explicit pagination:__ + ```java + ts.find() + .isOpen() + .setPage(1) + .setPageSize(10) + .get(); + ``` + +??? warning "default pagination" + many systems have an implicit default pagination enabled, + which could block you from simply getting _all_ tickets. + + !!! tip + you can ask the `TicketSystem` object, to tell you if it uses a default pagination: + ```java + ts.hasDefaultPagination(); + ``` -- GitLab From 49a7367c8f91469d810dbc8446847e568f20779d Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Thu, 26 Nov 2020 14:05:56 +0100 Subject: [PATCH 17/42] refactor(docs): api: core: write 'TicketSystem' --- docs/api/core/ticket-system.md | 154 ++++++++++++++++++++++++++++++++- 1 file changed, 152 insertions(+), 2 deletions(-) diff --git a/docs/api/core/ticket-system.md b/docs/api/core/ticket-system.md index 3628c58..12a2953 100644 --- a/docs/api/core/ticket-system.md +++ b/docs/api/core/ticket-system.md @@ -1,4 +1,154 @@ # Ticketsystem -!!! todo - write usage api docs +A `TicketSystem` object represents a connection definition to a space in an external ticket system. +Part of this is a base URL, and some system specific identifier for e.g. a project on that system. +If the access needs some kind of authentication, +this has to be configured in this object on creation. + +## create new instance + +The constructor of `TicketSystem` is not publicly callable. +Acquiring an instance has to be done either by passing an URI or using the builder mechanism. + +### by URI + +This library has a global definition, for how an URI has to start. +The end of it is defined by each system specific implementation. + +!!! info "global URI definition" + `unifiedticketing::` + _For system specific details look into the systems part of this docs_ + +To instantiate a `TicketSystem` from an URI, call the static method `fromUri(String)`: + +```java +TicketSystem ts = TicketSystem.fromUri(); +``` + +!!! warning + If the given String does not match the criteria for a valid URI, + or the system identifier is unknown, it throws an `AssertionException` + +### by builder + +The library has a builder mechanism defined to instantiate a new `TicketSystem` object, using fluent-api. +To start it, call the static method `fromBuilder()`. +The returning object gives you all supported systems as choice, +which then brings you to the system specific builder mechanism. + +At the end, you'll have to finish the building process with a call to `build()`. + +!!! warning + If not all mandatory information where given before calling `build()`, + it will throw an `AssertionException` + +## configuration options + +You can set configurations of two kinds: + +- simple boolean switches to enable/disable a behaviour/feature +- string values + +To set a configuration, call the instance method `config`. It provides two signatures: + +- `config(TicketSystem.ConfigurationOption, boolean)` +- `config(TicketSystem.ConfigurationOption, String)` + +??? abstract "currently available configuration options" + | ConfigurationOption | type | default | description | + | :------------------- | :------ | :------ | :------------------------------------------------------------------------------------------------ | + | RETURN_NULL_ON_ERROR | boolean | `false` | If true, don't throw exception on error, but return null or the calling object, if in fluent-api. | + +!!! warning + option `RETURN_NULL_ON_ERROR` is not fully implemented and tested yet. + Expect it still throws Exceptions sometimes, but returns null/self also sometimes. +## list tickets + +Tickets are requested by using the filter mechanism. +To get _all_ Tickets just don't define any filters before calling `get()`. +They are returned as `List`. + +??? warning "default pagination" + many systems have an implicit default pagination enabled, + which could block you from simply getting _all_ tickets. + + you can ask the `TicketSystem` object, to tell you if it uses a default pagination: + + ```java + ts.hasDefaultPagination(); + ``` + +!!! example "requesting tickets" + ```java + ts.find() + .setPage(1) + .setPageSize(10) + .get(); + ``` + +You can add various filter options, before finally calling `get()`. +Each supported systems implementation is free to define special filter options. +These are only callable, if your variable has the dedicated child-type. + +The globally available ones are listed below. +They are marked `single` or `multi` types. +A `single` typed filter will override previous values, +whereas `multi` typed ones will be added to the previous values. + +| filter option method definition | type | description | +| :------------------------------- | :------- | :--------------------------------------------------------------------------------------------------------------- | +| `isClosed()` | `single` | returns only tickets closed, or _considered_ closed by the system specific implementation | +| `isOpen()` | `single` | returns only tickets open, or _considered_ open by the system specific implementation | +| `setPage(int)` | `single` | page number of pagination to request | +| `setPageSize(int)` | `single` | page size of request to paginate with | +| `withAssigneeId(String)` | `multi` | tickets with given assigneeId as assignee.
On multiple calls ticket must have _ALL_ given ids as assignees | +| `withAssigneeName(String)` | `multi` | same as assigneeId above | +| `withDescriptionContain(String)` | `single` | substring the description has to contain | +| `withDescriptionMatch(String)` | `single` | fully qualified regular expression, the whole description has to match | +| `withId(String)` | `multi` | id a ticket must have.
multiple calls keeps tickets matching _any_ of the set ids | +| `withLabel(String)` | `multi` | label a ticket must have.
Multiple calls a ticket must have _all_ given labels | +| `withTitleContain(String)` | `single` | substring the title has to contain | +| `withTitleMatch(String)` | `single` | fully qualified regular expression, the whole title has to match | + +## get single ticket + +To request a single ticket the method `getTicketById` is provided, +available with two signatures: +- `getTicketById(String)` +- `getTicketById(int)` + +The integer variant is just for convenience, if you have the id as number. +It calls the String one with your number transformed. + +!!! example + ```java + Ticket t = ts.getTicketById("5"); + ``` + +## create new ticket + +The creation of a new Ticket is started by calling `createTicket()`. +This starts another fluid-api chain, +in which you can set everything your new ticket should contain. +The chain finishes calling `create()` at the end. + +!!! warning + if a mandatory information for ticket creation is not given, + prior calling `create()`, + an `AssertionException` is thrown. + +!!! example + ```java + Ticket t = ts.createTicket() + .title("some title") + .create(); + ``` + +Global available setters for ticket creation are: + +| method | additional information | +| :--------------------------------------------- | :---------------------------------------------------------------------- | +| `assignees(String[])` | array of assignee identifiers, check system specific part, what to pass | +| `description(String)` | | +| `labels(Set)`
`labels(String[])` | | +| `title(String)` | | -- GitLab From ec2a775d622b4b494fa8dac011645318269f8d54 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Thu, 26 Nov 2020 14:07:50 +0100 Subject: [PATCH 18/42] refactor(docs): api: core: remove classes which aren't specifically mentioned in user docs --- docs/api/core/filter.md | 4 ---- docs/api/core/registered-systems.md | 4 ---- docs/api/core/ticket-assignee.md | 4 ---- docs/api/core/ticket-builder.md | 4 ---- docs/api/core/ticket-system-builder.md | 4 ---- mkdocs.yml | 5 ----- 6 files changed, 25 deletions(-) delete mode 100644 docs/api/core/filter.md delete mode 100644 docs/api/core/registered-systems.md delete mode 100644 docs/api/core/ticket-assignee.md delete mode 100644 docs/api/core/ticket-builder.md delete mode 100644 docs/api/core/ticket-system-builder.md diff --git a/docs/api/core/filter.md b/docs/api/core/filter.md deleted file mode 100644 index e072a49..0000000 --- a/docs/api/core/filter.md +++ /dev/null @@ -1,4 +0,0 @@ -# Filter - -!!! todo - write usage api docs diff --git a/docs/api/core/registered-systems.md b/docs/api/core/registered-systems.md deleted file mode 100644 index d12cd63..0000000 --- a/docs/api/core/registered-systems.md +++ /dev/null @@ -1,4 +0,0 @@ -# Registered Systems - -!!! todo - write usage api docs diff --git a/docs/api/core/ticket-assignee.md b/docs/api/core/ticket-assignee.md deleted file mode 100644 index 58c4449..0000000 --- a/docs/api/core/ticket-assignee.md +++ /dev/null @@ -1,4 +0,0 @@ -# Ticket Assignee - -!!! todo - write usage api docs diff --git a/docs/api/core/ticket-builder.md b/docs/api/core/ticket-builder.md deleted file mode 100644 index f59c52a..0000000 --- a/docs/api/core/ticket-builder.md +++ /dev/null @@ -1,4 +0,0 @@ -# Ticket-Builder - -!!! todo - write usage api docs diff --git a/docs/api/core/ticket-system-builder.md b/docs/api/core/ticket-system-builder.md deleted file mode 100644 index a9c6743..0000000 --- a/docs/api/core/ticket-system-builder.md +++ /dev/null @@ -1,4 +0,0 @@ -# Ticketsystem-Builder - -!!! todo - write usage api docs diff --git a/mkdocs.yml b/mkdocs.yml index 66c52d8..3ca7ecb 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -20,14 +20,9 @@ nav: - API: - Index: 'api/index.md' - Core: - - Filter: 'api/core/filter.md' - Logging: 'api/core/logging.md' - - Registered Systems: 'api/core/registered-systems.md' - Ticket: 'api/core/ticket.md' - - Ticket Assignee: 'api/core/ticket-assignee.md' - - Ticket Builder: 'api/core/ticket-builder.md' - Ticketsystem: 'api/core/ticket-system.md' - - Ticketsystem Builder: 'api/core/ticket-system-builder.md' - Exceptions: 'api/exceptions.md' - Systems: - GitLab: -- GitLab From d924ead943b4d60ac4cc950421e1041a0da5acce Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Thu, 26 Nov 2020 17:20:27 +0100 Subject: [PATCH 19/42] refactor(docs): api: core: write 'Ticket' --- docs/api/core/ticket.md | 57 +++++++++++++++++++++++++++++++++++++++-- 1 file changed, 55 insertions(+), 2 deletions(-) diff --git a/docs/api/core/ticket.md b/docs/api/core/ticket.md index 94e7a54..38c58aa 100644 --- a/docs/api/core/ticket.md +++ b/docs/api/core/ticket.md @@ -1,4 +1,57 @@ # Ticket -!!! todo - write usage api docs +A ticket instance represents one ticket of the connected space. + +## get/create ticket + +The class is not publicly constructable, +as it always belongs to a `TicketSystem` object. + +Getting an instance for a existing ticket, +or creating a new one, +is done from a `TicketSystem` instance. +[->For details see here <-](./ticket-system.md) +## reading data + +There are various getters available. +Below the globally defined ones are listed, +each system specific implementation is free to provide additional ones. + +!!! warning + systems are not guaranteed to support all data, + a global getter is defined for. + Therefore it can happen, you get an null value back + or exception thrown in this case. + +| method | return | +| :----------------- | :-------------------- | +| `getAssignees()` | `Set` | +| `getDescription()` | `String` | +| `getId()` | `String` | +| `getLabels()` | `Set` | +| `getParent()` | `TicketSystem` | +| `getTitle()` | `String` | +| `isOpen()` | `boolean` | + +## changing data + +You can change data of supported fields through dedicated setters. +Every changed field is flagged as changed. +To persist the changes to the connected space, +you need to call `save()`. +This forms an update request for all flagged fields +and returns a new instance of `Ticket`, +formed off the answer from the connected system. + +Below the globally defined setters are listed, +each system implementation is free to offer more. + +| method | description | +| :-------------------------------------------------- | :-------------------------------------------------------------- | +| `addAssignee(String)`
`removeAssignee(String)` | adds/removes assignee, check system specific part, what to pass | +| `addLabel(String)` | add label | +| `clearAssignees()` | remove all assignees | +| `open()`
`close()` | opens/closes the ticket | +| `setDescription(String)` | | +| `setLabels(Set)`
`setLabels(String[])` | replace all labels with the passed ones | +| `setTitle(String)` | | -- GitLab From 24757abe6b3255886a6d38be05cabe479b6ab56f Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Fri, 27 Nov 2020 14:56:53 +0100 Subject: [PATCH 20/42] refactor(docs): api: core: write 'Logging' --- docs/api/core/logging.md | 41 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 39 insertions(+), 2 deletions(-) diff --git a/docs/api/core/logging.md b/docs/api/core/logging.md index a2dcffd..c11b3c4 100644 --- a/docs/api/core/logging.md +++ b/docs/api/core/logging.md @@ -1,4 +1,41 @@ # Logging -!!! todo - write usage api docs +The library uses the built-in logger from `java.util.logging`. +It configures to not use the parent logger and places a new ConsoleHandler +on static initialization. This outputs the log in formatted lines like: +```text +[2020-11-27T14:40:26+0100] [WARNING] [de.hftstuttgart.unifiedticketing.core.Logging.test] calling from app +``` + +This will _not_ change visual presentation based on any localization. + +## change log-level + +Default is to use _INFO_-level. +You can change the used level: +```java +Logging.setLevel(Level); +``` + +The parameter passed is of type `java.util.logging.Level`. + +## test logging output + +To test if the logging as such works, +you can pass a test string: +```java +Logging.test("test message"); +``` + +This message will be logged by the `Logging`-class own Logger, +once per level. + +## set custom formatter + +If you need another format, +you can replace the default formatter of this lib by calling: +```java +Logging.setFormatter(Formatter); +``` + +This formatter has to be of type `java.util.logging.Formatter` -- GitLab From 6e7c1318437986ebd0563512c53787f3b0bca4b2 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Fri, 27 Nov 2020 15:07:46 +0100 Subject: [PATCH 21/42] refactor(docs): api: write 'Exceptions' --- docs/api/exceptions.md | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/docs/api/exceptions.md b/docs/api/exceptions.md index 097d94d..4b4cc72 100644 --- a/docs/api/exceptions.md +++ b/docs/api/exceptions.md @@ -1,5 +1,23 @@ # Exceptions -!!! todo - - list exceptions available - - explain inheritance structure +The library defines its own set of exceptions. +Throughout the whole library, these are used. +They are located in the package `de.hftstuttgart.unifiedticketing.exceptions`. + +Base for all others is `UnifiedticketingException`, +which extends `RuntimeException`. +Every other custom exception extends this exception. + +This provides you with the ability, +to catch a specific or all library related problems. +Both without catching exceptions of your own code, +that happen to be in the same try block. + +## Possible Exceptions + +- `AssertionException` +- `DeserializationException` +- `HttpRequestException` +- `HttpResponseException` +- `SerializationException` +- `UnsupportedFunctionException` -- GitLab From 9ea817f08288e78c8741f12ae0ef753cb8b275d8 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Fri, 27 Nov 2020 18:42:20 +0100 Subject: [PATCH 22/42] refactor(docs): api: systems: gitlab: write 'TicketSystem' --- docs/api/systems/gitlab/ticket-system.md | 130 ++++++++++++++++++++++- 1 file changed, 127 insertions(+), 3 deletions(-) diff --git a/docs/api/systems/gitlab/ticket-system.md b/docs/api/systems/gitlab/ticket-system.md index 7901ec3..29071ca 100644 --- a/docs/api/systems/gitlab/ticket-system.md +++ b/docs/api/systems/gitlab/ticket-system.md @@ -1,4 +1,128 @@ -# Gitlab-Ticketsystem +# GitLab-Ticketsystem -!!! todo - write usage api docs +This documents GitLab specific things for the integration to this library. +For the global parts, see in the [core sections Ticketsystem site][core-ts]. + +## create new instance + +A `GitlabTicketSystem` object is always referencing a specific GitLab project. +Mandatory information to instantiate it, are the GitLab instances base url and the projects id. + +For public accessible actions, it can be used anonymously. +Other operations have to be authenticated using an api-key. + +For all calls the GitLab api V4 is used (at the time of writing this, the only available one). +If not configured otherwise, connections will use https. + +### by URI + +```java +// recommended option +GitlabTicketSystem ts = (GitlabTicketSystem) TicketSystem.fromUri(""); + +// second possible declaration +TicketSystem< + GitlabTicket, + GitlabTicketSystem, + GitlabTicketBuilder, + GitlabFilter + > gl = TicketSystem.fromUri(""); +``` + +The first declaration option uses the child-class from the GitLab implementation directly. +The second option uses the parent-class instead, +defining the different implementations with Generics. + +Use the first option, if you're sure you want to use GitLab no matter what. +This way you can see GitLab specific methods, +whereas the second option keeps you limited on the global defined ones. +If you may switch ticket systems in the future, +the second option forces you to not use system specific stuff, making a transition easier. + +The URI to pass has to match this format: +``` +unifiedticketing:gitlab:[http://|https://]:[:api key] +``` + +- protocol for http/https is optional. If not given, https is used +- base url can contain also non-standard port hosted gitlab instances +- api key if authentication needed, otherwise anonymous access is used + +??? example "URI examples" + - non-https anonymous, project 234, public gitlab + `unifiedticketing:gitlab:http://wwww.gitlab.com:234` + - implicit https authenticated, project 234, public gitlab + `unifiedticketing:gitlab:gitlab.com:234:1234896102765abcddbda324bb3a3` + - explicit https authenticated, project 42, fictional gitlab, non-standard port + `unifiedticketing:gitlab:https://gitlab.example.org:8080:42:1234896102765abcddbda324bb3a3` + +### by builder + +For instantiation from the builder, +mostly the same like building by URI applies. + +!!! warning + Passing the base url ensure the protocol (http or https) is removed + +??? example "builder examples" + - non-https anonymous, project 234, public gitlab + ```java + GitlabTicketSystem ts = TicketSystem.fromBuilder() + .gitlab() + .withBaseUrl("www.gitlab.com") + .withHttp() + .withProjectId(234) // String and int variant available + .build(); + ``` + - implicit https authenticated, project 234, public gitlab + ```java + GitlabTicketSystem ts = TicketSystem.fromBuilder() + .gitlab() + .withBaseUrl("gitlab.com") + .withProjectId("234") + .withApiKey("1234896102765abcddbda324bb3a3") + .build(); + ``` + - explicit https authenticated, project 42, fictional gitlab, non-standard port + ```java + GitlabTicketSystem ts = TicketSystem.fromBuilder() + .gitlab() + .withBaseUrl("gitlab.example.org:8080") + .withHttps() + .withProjectId(42) + .withApiKey("1234896102765abcddbda324bb3a3") + .build(); + ``` + +## list tickets + +!!! warning "default pagination" + GitLab has a default pagination on _20_ elements per page. + Highest possible value is _100_ elements. [[Link]][gl-api-docs-pagination] + +!!! warning "mutual exclusive filters" + if you filter for assignees, you can only use either assignee-ids or their usernames. [[Link]][gl-api-docs-issues-list] + +## get single ticket + +!!! info + This uses the list mechanism internally, + with the given issue-id as filter and just unwraps it from the received list. + +## create new ticket + +For a new GitLab ticket a title is mandatory. +Everything else is optional. + +!!! example "minimal example" + ```java + GitlabTicket = ts.createTicket() + .title("my new ticket") + .create(); + ``` + +Setting an assignee, has to be by user-id. Setting by user name is not supported. + +[core-ts]: ../../core/ticket-system.md +[gl-api-docs-issues-list]: https://docs.gitlab.com/ee/api/issues.html#list-issues +[gl-api-docs-pagination]: https://docs.gitlab.com/ee/api/#pagination -- GitLab From 8089a44472d6fa5bd0bf71b5291bcccb5d389ec8 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Sun, 29 Nov 2020 12:10:29 +0100 Subject: [PATCH 23/42] refactor(docs): api: core: add info about assignee object --- docs/api/core/ticket-system.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/api/core/ticket-system.md b/docs/api/core/ticket-system.md index 12a2953..17d4790 100644 --- a/docs/api/core/ticket-system.md +++ b/docs/api/core/ticket-system.md @@ -78,6 +78,11 @@ They are returned as `List`. ts.hasDefaultPagination(); ``` +!!! info "assignees" + Tickets have a field of type `Assignee`. + These have final String fields, + where the system implementation puts values if supported. + !!! example "requesting tickets" ```java ts.find() -- GitLab From 840053ed84db7ffbb45b47695a576e6072c45aa1 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Sun, 29 Nov 2020 12:10:59 +0100 Subject: [PATCH 24/42] refactor(docs): api: systems: gitlab: add info about assignee object --- docs/api/systems/gitlab/ticket-system.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/api/systems/gitlab/ticket-system.md b/docs/api/systems/gitlab/ticket-system.md index 29071ca..5f6cf36 100644 --- a/docs/api/systems/gitlab/ticket-system.md +++ b/docs/api/systems/gitlab/ticket-system.md @@ -103,6 +103,10 @@ mostly the same like building by URI applies. !!! warning "mutual exclusive filters" if you filter for assignees, you can only use either assignee-ids or their usernames. [[Link]][gl-api-docs-issues-list] +!!! info "assignees" + GitLab implementation supports the fields `id`, `username` and `full name`. + If ticket has no assignee, assignee field stays `null`. + ## get single ticket !!! info -- GitLab From 57148591e176eb3ac99e1ad59b9a56b6504c73f2 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Sun, 29 Nov 2020 12:12:19 +0100 Subject: [PATCH 25/42] refactor(docs): api: systems: remove seperate sites for parts described in others yet --- docs/api/systems/gitlab/ticket-assignee.md | 4 ---- docs/api/systems/gitlab/ticket-builder.md | 4 ---- docs/api/systems/gitlab/ticket-system-builder.md | 4 ---- mkdocs.yml | 3 --- 4 files changed, 15 deletions(-) delete mode 100644 docs/api/systems/gitlab/ticket-assignee.md delete mode 100644 docs/api/systems/gitlab/ticket-builder.md delete mode 100644 docs/api/systems/gitlab/ticket-system-builder.md diff --git a/docs/api/systems/gitlab/ticket-assignee.md b/docs/api/systems/gitlab/ticket-assignee.md deleted file mode 100644 index b35aa76..0000000 --- a/docs/api/systems/gitlab/ticket-assignee.md +++ /dev/null @@ -1,4 +0,0 @@ -# Gitlab-Ticket Assignee - -!!! todo - write usage api docs diff --git a/docs/api/systems/gitlab/ticket-builder.md b/docs/api/systems/gitlab/ticket-builder.md deleted file mode 100644 index 720dcde..0000000 --- a/docs/api/systems/gitlab/ticket-builder.md +++ /dev/null @@ -1,4 +0,0 @@ -# Gitlab-Ticket-Builder - -!!! todo - write usage api docs diff --git a/docs/api/systems/gitlab/ticket-system-builder.md b/docs/api/systems/gitlab/ticket-system-builder.md deleted file mode 100644 index 28e1f0a..0000000 --- a/docs/api/systems/gitlab/ticket-system-builder.md +++ /dev/null @@ -1,4 +0,0 @@ -# Gitlab-Ticketsystem-Builder - -!!! todo - write usage api docs diff --git a/mkdocs.yml b/mkdocs.yml index 3ca7ecb..e9290df 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -28,10 +28,7 @@ nav: - GitLab: - Filter: 'api/systems/gitlab/filter.md' - Ticket: 'api/systems/gitlab/ticket.md' - - Ticket Assignee: 'api/systems/gitlab/ticket-assignee.md' - - Ticket Builder: 'api/systems/gitlab/ticket-builder.md' - Ticketsystem: 'api/systems/gitlab/ticket-system.md' - - Ticketsystem Builder: 'api/systems/gitlab/ticket-system-builder.md' - Developers Guide: - Index: 'developers-guide.md' -- GitLab From 8c5f8386da0569b071051cdb926f93f37f4a4d39 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Sun, 29 Nov 2020 12:34:44 +0100 Subject: [PATCH 26/42] refactor(docs): api: systems: gitlab: add hint about local filtrs to ticket-system, remove seperate filter file --- docs/api/systems/gitlab/filter.md | 4 ---- docs/api/systems/gitlab/ticket-system.md | 6 ++++++ mkdocs.yml | 1 - 3 files changed, 6 insertions(+), 5 deletions(-) delete mode 100644 docs/api/systems/gitlab/filter.md diff --git a/docs/api/systems/gitlab/filter.md b/docs/api/systems/gitlab/filter.md deleted file mode 100644 index 40c876b..0000000 --- a/docs/api/systems/gitlab/filter.md +++ /dev/null @@ -1,4 +0,0 @@ -# Gitlab-Filter - -!!! todo - write usage api docs diff --git a/docs/api/systems/gitlab/ticket-system.md b/docs/api/systems/gitlab/ticket-system.md index 5f6cf36..8ab3d36 100644 --- a/docs/api/systems/gitlab/ticket-system.md +++ b/docs/api/systems/gitlab/ticket-system.md @@ -107,6 +107,12 @@ mostly the same like building by URI applies. GitLab implementation supports the fields `id`, `username` and `full name`. If ticket has no assignee, assignee field stays `null`. +From the filters shown on the global `TicketSystem` docs, +the ones for regex-matching are not natively supported by the GitLab API. +If such a filter is used, +this get's done locally after receiving the response from GitLab, +before handing it to the user. + ## get single ticket !!! info diff --git a/mkdocs.yml b/mkdocs.yml index e9290df..03705e1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -26,7 +26,6 @@ nav: - Exceptions: 'api/exceptions.md' - Systems: - GitLab: - - Filter: 'api/systems/gitlab/filter.md' - Ticket: 'api/systems/gitlab/ticket.md' - Ticketsystem: 'api/systems/gitlab/ticket-system.md' - Developers Guide: -- GitLab From 97b5a606dcca206d9602bd7f1f0730ac0a436d6c Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Sun, 29 Nov 2020 14:08:54 +0100 Subject: [PATCH 27/42] refactor(docs): indent markdown-extensions block in mkdocs.yml --- mkdocs.yml | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 03705e1..2570b0e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -43,18 +43,18 @@ theme: icon: library_books markdown_extensions: -- admonition -- codehilite: - linenums: true -- toc: - permalink: True -- footnotes -- tables -- plantuml_markdown: - server: http://plantuml.com/plantuml - format: svg -- pymdownx.emoji: - emoji_generator: !!python/name:pymdownx.emoji.to_svg -- pymdownx.tasklist -- pymdownx.details -- pymdownx.superfences + - admonition + - codehilite: + linenums: true + - toc: + permalink: True + - footnotes + - tables + - plantuml_markdown: + server: http://plantuml.com/plantuml + format: svg + - pymdownx.emoji: + emoji_generator: !!python/name:pymdownx.emoji.to_svg + - pymdownx.tasklist + - pymdownx.details + - pymdownx.superfences -- GitLab From 21de3de7a91333f6dc100c678319baeef9fc24f8 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Sun, 29 Nov 2020 14:38:54 +0100 Subject: [PATCH 28/42] refactor(docs): dev-guide: move to own directory --- docs/{developers-guide.md => developers-guide/index.md} | 0 mkdocs.yml | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename docs/{developers-guide.md => developers-guide/index.md} (100%) diff --git a/docs/developers-guide.md b/docs/developers-guide/index.md similarity index 100% rename from docs/developers-guide.md rename to docs/developers-guide/index.md diff --git a/mkdocs.yml b/mkdocs.yml index 2570b0e..2bd6c2b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -29,7 +29,7 @@ nav: - Ticket: 'api/systems/gitlab/ticket.md' - Ticketsystem: 'api/systems/gitlab/ticket-system.md' - Developers Guide: - - Index: 'developers-guide.md' + - Index: 'developers-guide/index.md' theme: name: 'material' -- GitLab From 6a214f11fe32c18a50df14ca1a91213373db14ef Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Sun, 29 Nov 2020 14:39:28 +0100 Subject: [PATCH 29/42] refactor(docs): dev-guide: write initial styleguide page --- docs/developers-guide/styleguide.md | 85 +++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 86 insertions(+) create mode 100644 docs/developers-guide/styleguide.md diff --git a/docs/developers-guide/styleguide.md b/docs/developers-guide/styleguide.md new file mode 100644 index 0000000..4995d1b --- /dev/null +++ b/docs/developers-guide/styleguide.md @@ -0,0 +1,85 @@ +# Styleguide + +If not explicitly stated otherwise, +the following takes effect for all files: + +- character encoding __utf-8__ +- line endings with __lf__ +- indentation with __4 spaces__ +- final new line + +In general, +it's a good idea to have a look into the yet existing code, +to check how certain things were done up to now. + +## Java + +The most important thing to say here is: opening braces are written into the next line. +_(more to come if s.o. does s.th. differently I didn't think of)_ + +## Markdown + +!!! info "Todo" + write docs + +most important bullet points: + +- leave always an empty line above and beneath of lists. + It may render fine in normal markdown viewers, + but not in the MkDocs Pages docs (like this) + + ??? example inline end + __bad:__ + ```markdown + some text + - bullet point + - another item + more normal text + ``` + __good:__ + ```markdown + some text + + - bullet point + - another item + + more normal text + ``` + +- if you insert a link, + __always__ write the link to the bottom of the file with an alias, + ordered alphabetically. + + ??? example + __bad:__ + ```markdown + Look [here](https://www.coolsite.not/with/ultra/long/url) to read more about this. + ``` + __good:__ + ```markdown + Look [here][coolsite] to read more about this. + + [coolsite]: https://www.coolsite.not/with/ultra/long/url + ``` + +- split long sentences on punctuation and connection words like `and` & `or`. + It will have the same appearance in viewers, + but be much easier to maintain on code side. + + ??? example + __bad__: + ```markdown + Some sentence that is very long, therefore it has punctuation and has absolutely no sense at all. + ``` + > Some sentence that is very long, therefore it has punctuation and has absolutely no sense at all. + + __good:__ + ```markdown + Some sentence that is very long, + therefore it has punctuation + and has absolutely no sense at all. + ``` + + > Some sentence that is very long, + > therefore it has punctuation + > and has absolutely no sense at all. diff --git a/mkdocs.yml b/mkdocs.yml index 2bd6c2b..e162497 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -30,6 +30,7 @@ nav: - Ticketsystem: 'api/systems/gitlab/ticket-system.md' - Developers Guide: - Index: 'developers-guide/index.md' + - Styleguide: 'developers-guide/styleguide.md' theme: name: 'material' -- GitLab From 373d981adee6daa0aec15cac80d4d25fd9bd4769 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Mon, 30 Nov 2020 10:58:38 +0100 Subject: [PATCH 30/42] refactor(docs): add markdown-del-ins extension for strike through text --- mkdocs.yml | 1 + requirements.txt | 1 + 2 files changed, 2 insertions(+) diff --git a/mkdocs.yml b/mkdocs.yml index e162497..3779c4f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -47,6 +47,7 @@ markdown_extensions: - admonition - codehilite: linenums: true + - markdown_del_ins - toc: permalink: True - footnotes diff --git a/requirements.txt b/requirements.txt index 916d0f1..af46b99 100644 --- a/requirements.txt +++ b/requirements.txt @@ -5,3 +5,4 @@ plantuml~=0.2 plantuml-markdown~=3.1 pymdown-extensions~=6.2 certifi~=2019.9 +markdown_del_ins~=1.0 -- GitLab From e10fe74f53fff998202dee1597ca69db467c6436 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Mon, 30 Nov 2020 10:59:00 +0100 Subject: [PATCH 31/42] refactor(docs): order requirements file alphabetically --- requirements.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/requirements.txt b/requirements.txt index af46b99..4caafdb 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,8 +1,8 @@ +certifi~=2019.9 +markdown_del_ins~=1.0 Markdown~=3.1 -mkdocs~=1.0 mkdocs-material~=4.0 -plantuml~=0.2 +mkdocs~=1.0 plantuml-markdown~=3.1 +plantuml~=0.2 pymdown-extensions~=6.2 -certifi~=2019.9 -markdown_del_ins~=1.0 -- GitLab From 3ea3058a3cfc719baaec87c2c46243f1906b596c Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Mon, 30 Nov 2020 11:14:44 +0100 Subject: [PATCH 32/42] chore: add editorconfig --- .editorconfig | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 .editorconfig diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..0792692 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,16 @@ +# Editor configuration, see https://editorconfig.org +root = true + +[*] +charset = utf-8 +indent_style = space +indent_size = 4 +insert_final_newline = true +trim_trailing_whitespace = true + +[*.ts] +quote_type = single + +[*.md] +max_line_length = off +trim_trailing_whitespace = false -- GitLab From 4344d0ae88e57d2f80dc285aeba84f34cd3ccca9 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Mon, 30 Nov 2020 11:15:10 +0100 Subject: [PATCH 33/42] chore: add standard-version config file --- .versionrc | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 .versionrc diff --git a/.versionrc b/.versionrc new file mode 100644 index 0000000..7428f00 --- /dev/null +++ b/.versionrc @@ -0,0 +1,3 @@ +{ + "tagPrefix": "" +} -- GitLab From c6b689c3f9d140b9a58f7aa80703011b29c07dbc Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Mon, 30 Nov 2020 12:03:29 +0100 Subject: [PATCH 34/42] refactor(docs): dev-guide styleguide: del left todo mark --- docs/developers-guide/styleguide.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/developers-guide/styleguide.md b/docs/developers-guide/styleguide.md index 4995d1b..757f531 100644 --- a/docs/developers-guide/styleguide.md +++ b/docs/developers-guide/styleguide.md @@ -19,9 +19,6 @@ _(more to come if s.o. does s.th. differently I didn't think of)_ ## Markdown -!!! info "Todo" - write docs - most important bullet points: - leave always an empty line above and beneath of lists. -- GitLab From 621fd4b1a04a00a9d7bcf7b98bffb996d86a75a6 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Mon, 30 Nov 2020 12:05:38 +0100 Subject: [PATCH 35/42] refactor(docs): dev-guide: styleguide: add markdown table example --- docs/developers-guide/styleguide.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/developers-guide/styleguide.md b/docs/developers-guide/styleguide.md index 757f531..85c4e4d 100644 --- a/docs/developers-guide/styleguide.md +++ b/docs/developers-guide/styleguide.md @@ -80,3 +80,20 @@ most important bullet points: > Some sentence that is very long, > therefore it has punctuation > and has absolutely no sense at all. + +- tables have to be formatted in code + + ??? example + __bad:__ + ```markdown + ||column 1| + |:-|:-| + |__row 1__|cell 1| + ``` + + __good:__ + ```markdown + | | column 1 | + | :-------- | :------- | + | __row 1__ | cell 1 | + ``` -- GitLab From db2f220fee179ae3bbee22a5a009dc13369ac7f8 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Mon, 30 Nov 2020 18:20:23 +0100 Subject: [PATCH 36/42] refactor(docs): update mkdocs, reorder config entries, ... --- docs/index.md | 16 ++++++++-------- mkdocs.yml | 42 ++++++++++++++++++++++-------------------- requirements.txt | 6 +++--- 3 files changed, 33 insertions(+), 31 deletions(-) diff --git a/docs/index.md b/docs/index.md index 2a6ab79..f45076a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -47,15 +47,15 @@ if you decide to contribute to it. This library and it's development belongs to the University of Applied Sciences Stuttgart. It was originally developed as bachelors-thesis by Lukas Wiest -[e-mail][9l5-hft-mail] -[Twitter][9l5Twitter] -[GitHub][9l5GH] -[GitLab][9l5GL]. +[:material-email-send:{: style="color: black"}][9l5-hft-mail] +[:fontawesome-brands-twitter:{: style="color: #1DA1F2"}][9l5Twitter] +[:fontawesome-brands-github:{: style="color: black"}][9l5GH] +[:fontawesome-brands-gitlab:{: style="color: orange"}][9l5GL]. The guardian professor was Prof. Dr. Gero Lueckemeyer -[e-mail][lueck-hft-mail] -[university profile][lueck-hft-profile] -[GitHub][lueck-GH] -[Xing][lueck-Xing]. +[:material-email-send:{: style="color: black"}][lueck-hft-mail] +[:fontawesome-solid-university:{: style="color: black"}][lueck-hft-profile] +[:fontawesome-brands-github:{: style="color: black"}][lueck-GH] +[:fontawesome-brands-xing:{: style="color: teal"}][lueck-Xing]. He is the current maintainer for this project and the appropriate contact for questions, access request, etc. [9l5-hft-mail]: mailto:62wilu1bif@hft-stuttgart.de diff --git a/mkdocs.yml b/mkdocs.yml index 3779c4f..11be2fd 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,16 +1,15 @@ site_name: Unified Ticketing Docs +docs_dir: docs +edit_uri: 'blob/master/docs/' repo_name: 'Code on Transfer Portal' repo_url: 'https://transfer.hft-stuttgart.de/gitlab/9Lukas5/unified-ticketing' -edit_uri: 'blob/master/docs/' -docs_dir: docs copyright: 'Copyright © 2020 University for Applied Sciences Stuttgart' use_directory_urls: false nav: - - Index: 'index.md' - Home: - Index: 'index.md' - Changelog: 'unified-ticketing/changelog-softlink.md' @@ -33,30 +32,33 @@ nav: - Styleguide: 'developers-guide/styleguide.md' theme: + features: + - navigation.tabs + icon: + logo: material/book-open + language: 'en' name: 'material' palette: - primary: 'white' - accent: 'teal' - language: 'en' - feature: - tabs: true - logo: - icon: library_books + accent: 'blue' + primary: 'red' markdown_extensions: - admonition - - codehilite: - linenums: true - - markdown_del_ins - - toc: - permalink: True + - attr_list - footnotes - - tables + - markdown_del_ins - plantuml_markdown: - server: http://plantuml.com/plantuml format: svg - - pymdownx.emoji: - emoji_generator: !!python/name:pymdownx.emoji.to_svg - - pymdownx.tasklist + server: http://plantuml.com/plantuml - pymdownx.details + - pymdownx.emoji: + emoji_index: !!python/name:materialx.emoji.twemoji + emoji_generator: !!python/name:materialx.emoji.to_svg + - pymdownx.highlight: + linenums: true - pymdownx.superfences + - pymdownx.tabbed + - pymdownx.tasklist + - toc: + permalink: True + - tables diff --git a/requirements.txt b/requirements.txt index 4caafdb..c67bf3f 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,8 +1,8 @@ -certifi~=2019.9 +certifi~=2020.11 markdown_del_ins~=1.0 Markdown~=3.1 -mkdocs-material~=4.0 +mkdocs-material~=6.0 mkdocs~=1.0 plantuml-markdown~=3.1 plantuml~=0.2 -pymdown-extensions~=6.2 +pymdown-extensions~=8.0 -- GitLab From 3a525bd198b46e2adb1efd79cd4badb78da8c773 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Tue, 1 Dec 2020 13:23:45 +0100 Subject: [PATCH 37/42] refactor(docs): dev-guide: write workflow --- docs/developers-guide/workflow.md | 397 ++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 398 insertions(+) create mode 100644 docs/developers-guide/workflow.md diff --git a/docs/developers-guide/workflow.md b/docs/developers-guide/workflow.md new file mode 100644 index 0000000..7373caa --- /dev/null +++ b/docs/developers-guide/workflow.md @@ -0,0 +1,397 @@ +# Workflow + +This project is maintained in a GitLab repository, +hosted on the [M4Lab's][m4lab] [Transfer-Portal][tr-portal] [GitLab instance][tr-gitlab]. +Source code for the maven Java library and the markdown docs are managed together in a [single repository][lib-repo-home]. + +This page tells you for the different parts of this project, +how to do it. +The following applies project wide: + +- language is english: code, comments, documentation, tickets, discussion, ... + +## Git/GitLab + +!!! danger "disclaimer" + There are a few rules any developer HAS TO follow, + in order to get any chance his merge-requests will be accepted. + +This project is managed using Git, hosted on the universities GitLab instance. + +### Issues/Merge Requests handling + +Project management happens in the GitLab repositories issue board. + +First of all, make sure for everything you do a ticket exists. +Extending this, also check regularly your tickets are: + +- assigned to you +- are in the correct column + +There are three columns as of writing this documentation: `To Do`, `Doing` and `review`. +Planning something, a new ticket get's created and placed into the `To Do` column. + +If you start to work on this ticket + +- move it to `Doing` +- create a new feature branch from the master + - named like: `-` +- push the new branch +- create a new merge request + - title starting with `wip: ` + - description containing `closes #` + - assign it to you (even if you're not able to merge) +- start working + +After implementing your change + +- move your ticket to `review` column +- change your merge requests labels: remove `Doing` and add `review` +- change assignee to someone to review your work + +### Branch Names + +Branches should always start with the number of the related ticket, followed by a dash. +This way the branch get's automatically shown in the ticket. + +### Committing + +!!! tip "golden rules" + - __many small__ > ~~few big~~ commits + - unrelated changes in separate commit + +We encourage everyone to make heavy use of `git status` and `git diff`. +Please always check before committing, what exactly you have changed. +What we won't accept: + +- whole file content removed and added back + This most likely happens if you make great use of auto format, + messing everything up. + Another one error source is something changed line endings. +- empty lines containing spaces, or trailing spaces on line end (without technical reason) + No big deal to fix, but time waste if we have to block your MR because of this. +- multiple changes in one commit, that have nothing to do with each other + Great you have fixed a typo in a comment at the other end of the file. + What do you think happens, if five people fix the same typo in their commits? + We would have four merge conflicts, needing manual work to fix this mess. + So create a new ticket for what you found, + instead of just doing it as it doesn't hurt. + It hurts, trust me. +- commit messages not following conventional commits specification + +!!! tip "view diff of not yet tracked files" + If you want to check a new file for flaws, sure `git diff` doesn't show anything. + But you can add the file and before committing check with `git diff --cached`. + +!!! tip "add only parts of changes in a file" + As we want to have more small commits, than one single big one, + it can be useful to split your changes into multiple commits, + even inside the same file. + You can use `git add -p [path|file]`. + This allows you to exactly decide which lines of your changes should be staged + , before committing. + +#### Commit Messages + +We use the [conventional commits][conv-comm] specification in this repository, +to auto generate a changelog with [conventional-changelog][conv-change]. + +### Protected Branches/Tags + +The repository has the master branch and release tags (format `^[0-9]+\.[0-9]+\.[0-9]+$`) +protected to project maintainers. + +### Branching-Model + +We use a branch per feature based branching model. +Base and target to merge is always latest `master`. + +## Java Development + +First step before changing the source code, +would be to check if there's something going on yet, +or this topic possibly was discussed yet and abandoned for some reason. +For this, check the [defined GitLab workflow](#gitgitlab). + +This library is a maven project. +In order to contribute to it, +make sure your machine is setup according to the [setup guide][setup-guide]. + +### Change an existing functionality + +- check with the [source structure below](#source-code-structure), + where to find the part you want to change. +- make your changes +- make sure all unittests still pass +- commit your changes following the Git/GitLab workflow defined. + +### Add integration for new system + +- familiarize with the [code structure](#source-code-structure) +- create a new package under `de.hftstuttgart.unifiedticketing.systems`, + identifying the new system +- prepare to implement all abstract classes from the `core` package + - class names have to be the same as the `core` ones, + prefixed with the identifier you named your package after +- create unittests for the planned integration, + either by putting a `fail();` into each testmethod, + or really writing tests first for TDD +- commit & push this skeleton-like state +- create WIP merge-request +- implement + +### Source code structure + +After cloning the repository, +you'll have to open/import an existing maven project in your IDE of choice. +There WILL NOT be any configuration files for a specific IDE committed into the code. +In regards to the maven project parts, +only the `pom.xml` and the contents under `/src` are committed. + +The main package for everything of this library is `de.hftstuttgart.unifiedticketing`. +Beneath it is split into three sub-packages: + +| subpackage | content | +| :----------- | :------------------------------------------------------------------------- | +| `core` | root classes defining lib core, generic public interface | +| `exceptions` | library own exceptions | +| `systems` | subpackage per system integration, implementation of abstract core-classes | + +__core:__ +The majority of the classes are abstract ones. +They define the generic interface available to the user of this lib. +Logic identical for all system integrations are found in these classes. +Only few methods are really declared abstract, +in most cases it's the part calling the external system. + +__exceptions:__ +The library defines its own exceptions, based on `RuntimeException`. +If you throw any exception, +__only__ use exceptions from this package, +never anything else. + +If you miss an exception you'd like to throw, +add a new one that extends `UnifiedTicketingException`. + +__systems:__ +Each system that's integrated into this lib, +will have a sub-package under `de.hftstuttgart.unifiedticketing.systems`. +In this very own package every abstract class from the `core`-package has to be implemented. +Apart from that, +every system can define as many helper classes +or additional sub-packages. + +### Unittests + +The logical code is structured under `/src/main/java`. +For unittests the same package structure is created under `/src/test/java`. +Tests are written using the `jupiter-engine` from JUnit5, +combined with `Mockito3`. + +- test-classes are named identical to the class under test, + suffixed with `Test` +- test-classes have to be in the same package than the class under test + +What has to be tested: + +- constructors +- getters/setters +- calculations/transformations/... +- fluent-api to return the same instance +- serializing request data before request +- failing web-request +- successful web-request & deserializing of received data + +!!! warning "testing external resources" + All tests _have to_ run offline. + To test external resources, + e.g. a web-request, + use Mockito to block the code under test to really access the external resource + and transparently return your mock answer expected for the assertions following. + +??? tip "test abstract classes" + To test non-abstract code of abstract classes, + you can instantiate a mock of it through Mockito, + set to call the real methods: + + ```java + instance = mock(ClassUnderTest.class, + withSettings().useConstructor().defaultAnswer(CALLS_REAL_METHODS)); + ``` + +## Documentation + +Documentation for the project is done entirely in Markdown +and rendered through MkDocs to a Website. +The repository global `README.md` just points to the documentation root, +which is `/docs/index.md`. +The same applies for the `CONTRIBUTING.md`. +`CHANGELOG.md` and `LICENSE.md` are kept with content in project root, +they are linked with a relative soft-link into the documentation folder. + +Files related to the documentation: + +| path | description | +| :----------------- | :---------------------------------------------- | +| `mkdocs.yml` | configuration file for mkdocs | +| `requirements.txt` | needed pypi packages to pass to pip for install | +| `/docs/**/*` | documentation files | +| `/docs/index.md` | Pages root | + +With the aim to give the documentation an appealing appearance, +additional to the default markdown specification, +a few extensions are enabled in the mkdocs config. +Please have a look at them and make use of, +where it seems adequate. +Reference for them can be found in the [MkDocs-Material site][mat-mkdocs-ext-ref]. + +To make any kind of diagram, sketch or similar, +use [PlantUML][puml]. +You have to surround the PlantUML code with code fences, +marked as `plantuml` as language identifier. +Then they will be rendered into an svg on pages creation. + +!!! bug + I tried to put this into an collapsed example admonition, + but the PlantUML diagram get's always placed outside the admonition. + Same applies for a tabbed environment. + +Example: +__code:__ +`````` +```plantuml +queue "write\nmarkdown" as write +queue "commit/push/\nmerge changes" as update +queue "pipeline\ntriggered" as cicd +queue "MkDocs\nMaterial" as MkDocsMat +queue "transpiled HTML\nonline" as deployed + +write -right-> update +update -right-> cicd +cicd -right-> MkDocsMat +MkDocsMat -right-> deployed +``` +`````` + +__result:__ +```plantuml +queue "write\nmarkdown" as write +queue "commit/push/\nmerge changes" as update +queue "pipeline\ntriggered" as cicd +queue "MkDocs\nMaterial" as MkDocsMat +queue "transpiled HTML\nonline" as deployed + +write -right-> update +update -right-> cicd +cicd -right-> MkDocsMat +MkDocsMat -right-> deployed +``` + +## Schedule a release + +For releases this project uses [standard-version][std-ver]. +This generates an automatic changelog based on the commits +and tags it. +The version of the library has three numbers +and has to follow the [semantic-version][semver] scheme. + +Tags marking a release have the format `^[0-9]+\.[0-9]+\.[0-9]+$`. +Pushing these tags is restricted in the GitLab Repo settings +for maintainers only. +Pushing a release tag triggers the CI/CD release pipeline for the maven project. + +## CI/CD + +This project uses GitLab-CI pipelines for + +- publishing the maven library to the repository own package registry +- deploying this pages documentation + +These pipelines are defined in several files: + +| file | content | +| :---------------------- | :------------------------------------------------------------ | +| `.gitlab-ci.yml` | root file, stages definition, include of other pipeline parts | +| `.gitlab-ci-maven.yml` | jobs regarding java library | +| `.gitlab-ci-mkdocs.yml` | jobs regarding pages documentation | + +pipeline graph overview: +```plantuml +rectangle "compile" as stageCompile { + ' maven + agent "maven:compile" as mvnCompile + + ' mkdocs + agent "mkdocs:compile" as mkdocsCompile +} +rectangle "test" as stageTest { + ' maven + agent "maven:test" as mvnTest + + ' mkdocs + agent "none" as mkdocsTest +} +rectangle "deploy" as stageDeploy { + ' maven + agent "maven:publish:master" as mvnPublMaster + agent "maven:publish:release" as mvnPublRelease + label "get's deployed with\n'devel' as version" as labelMvnPublMaster + label "get's deployed\nwith release version" as labelMvnPublRelease + + ' mkdocs + agent "mkdocs:bundle" as mkdocsBundle + agent "mkdocs:deploy" as mkdocsDeploy + label "creates tar archive as\ndownloadable job artifact" as labelMkdocsBundle + label "only triggered\non master branch" as labelMkdocsDeploy +} + +' maven pipeline connections +mvnCompile -right-> mvnTest +mvnTest -right-> mvnPublMaster +mvnTest -right-> mvnPublRelease + +mvnPublMaster -right- labelMvnPublMaster +mvnPublRelease -right- labelMvnPublRelease + +' mkdocs pipeline connections +mkdocsCompile -right-> mkdocsTest +mkdocsTest -right-> mkdocsBundle +mkdocsTest -right-> mkdocsDeploy + +mkdocsBundle -right- labelMkdocsBundle +mkdocsDeploy -right- labelMkdocsDeploy + +' compile stage keep in place +mvnCompile --[hidden]down- mkdocsCompile + +' test stage keep in place +mvnTest --[hidden]down-mkdocsTest + +' deploy stage keep in place +mvnPublMaster -[hidden]down- mvnPublRelease +mvnPublRelease -[hidden]down- mkdocsBundle +mkdocsBundle -[hidden]down- mkdocsDeploy +``` + +These jobs are defined with the `needs` keyword, +to make them only depend on exactly the needed previous jobs. +This makes it possible to run docs and library pipelines in parallel, +without waiting that all jobs of a stage must have finished before entering the next stage. + +With the `only` keyword the trigger of these pipelines is optimized, +to only run if necessary. +In general the final deployment jobs have configurations to run only on the secured branches/tags. +Additionally all jobs are configured to only run, +if changes on related files of this pipeline were made. + +[conv-comm]: https://www.conventionalcommits.org/en/v1.0.0/ +[conv-change]: https://github.com/conventional-changelog/conventional-changelog +[lib-repo-home]: https://transfer.hft-stuttgart.de/gitlab/9Lukas5/unified-ticketing/ +[m4lab]: https://www.hft-stuttgart.de/forschung/innovative-hochschule-m4-lab +[mat-mkdocs-ext-ref]: https://squidfunk.github.io/mkdocs-material/reference/abbreviations/ +[puml]: https://plantuml.com/ +[setup-guide]: /404.html +[semver]: https://semver.org/ +[std-ver]: https://github.com/conventional-changelog/standard-version +[tr-gitlab]: https://transfer.hft-stuttgart.de/gitlab/explore/projects +[tr-portal]: https://transfer.hft-stuttgart.de/ diff --git a/mkdocs.yml b/mkdocs.yml index 11be2fd..9d4f619 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -30,6 +30,7 @@ nav: - Developers Guide: - Index: 'developers-guide/index.md' - Styleguide: 'developers-guide/styleguide.md' + - Workflow: 'developers-guide/workflow.md' theme: features: -- GitLab From 8fe8d2c0b66bedc9841a9237c2bd954aece119e3 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Wed, 2 Dec 2020 15:03:50 +0100 Subject: [PATCH 38/42] refactor(docs): dev-guide: write machine setup --- docs/developers-guide/machine-setup.md | 255 +++++++++++++++++++++++++ mkdocs.yml | 2 +- 2 files changed, 256 insertions(+), 1 deletion(-) create mode 100644 docs/developers-guide/machine-setup.md diff --git a/docs/developers-guide/machine-setup.md b/docs/developers-guide/machine-setup.md new file mode 100644 index 0000000..5d1bb2a --- /dev/null +++ b/docs/developers-guide/machine-setup.md @@ -0,0 +1,255 @@ +# Machine Setup + +## General + +### Git + +The whole project is a Git repository, +to do anything you'll need to have Git setup on your machine. + +!!! tip + We highly recommend you use Git directly typing commands to your terminal, + instead of relying on any GUI tools, IDE integration's whatsoever. + They make life easy, sure. + But do you know, what exact calls they do under the hood? + +#### Installation + +=== "*nix" + Should be part of all major systems default software distribution path. + +=== "Windows" + !!! warning "disclaimer" + This is for people having not much experience. + If you e.g. use Cygwin, you could just install Git from there and ignore this^^ + + - Download Git: [Git-SCM][gitscm-win] + - Installation recommendations: + - opt-out from `Enable Git Credential Manager` + _We had bad experiences with it, storing wrong passwords an no one knew where to remove them as none of the pros used this thing^^_ + +#### Configuration + +After installing Git, you'll have to set a few information, +in order to be able to work with it. +Mandatory is your username and email. + +Globally set your most used username and email address you'll be using. + +```bash +git config --global user.name "" +git config --global user.email "" +``` + +!!! attention + If your global email is different from the one for this projects GitLab, + make sure to either add your main email address as committer email in your profile, + or change the git config for this project individually after cloning it. + +#### Clone project + +As of writing, the project can be accessed with HTTPS and SSH. +If this is not working, +check the repository from the link in the upper right corner of the page. +(Maybe the path changed and someone forgot to update this part of the docs) + +=== "SSH" + ```bash + git clone git@transfer.hft-stuttgart.de:9Lukas5/unified-ticketing.git + ``` + +=== "HTTPS" + ```bash + git clone https://transfer.hft-stuttgart.de/gitlab/9Lukas5/unified-ticketing.git + ``` + +## Java Development + +The Java library is development with OpenJDK 8 and Maven 3.6 + +### Requirements + +- Git setup +- OpenJDK 1.8.0+ +- Maven 3.6.0+ + +### Installation + +#### OpenJDK + +=== "*nix" + Check your specific systems package names. + + __Ubuntu 20.04__: + ```bash + sudo apt install openjdk-11-jdk + ``` + +=== "Windows" + + - download OpenJDK: [jdk.java.net][java-net] + - extract archive to permanent place + - create/update system environment variable `JAVA_HOME`, + to the path you extracted OpenJDK to. + - update `PATH` variable including the `bin` folder of your newly placed OpenJDK + - check with a terminal that `java --version` works + +#### Maven + +=== "*nix" + Same as before, check your specific systems package names. + + __Ubuntu:__ + ```bash + sudo apt install maven + ``` + +=== "Windows" + + - download Maven binary: [maven.apache.org][maven-dl] + - extract archive to permanent place + - create/update system environment variable `MAVEN_HOME`, + to the path you extracted Maven to. + - update `PATH` including `bin` folder of maven home + - check that `mvn --version` works + +### Import project to IDE + +Following is described, how to import the maven project to your IDE. +I really hope, you're familiar enough to know how to use your IDE, +so this is a just-in-case service. + +Also, this does not claim to be up-to-date/correct/cover all available IDE's. +You are invited to contribute to this list below +if you're IDE of choice is not listed yet or has some faults. + +=== "IntelliJ IDEA" + - Select `Open or Import` + - Choose the folder you cloned the project into + +## MkDocs (Documentation) + +This project is documented using MkDocs Material. +It means we write Markdown files, organize them in a configuration file +and MkDocs generates a static Website out of it we host and you are reading right now. + +### Requirements + +- Python 3.5+ +- pip +- Python virtual environment _(optional)_ + +### Installation + +=== "*nix" + check system specific names and commands, below are some examples collected over time: + + __Ubuntu:__ + ```bash + sudo apt install python3 python3-pip python3-venv + ``` + +=== "Windows" + - download & install Python: [python.org][python-win-dl] (use executable installer version) + +- open a terminal inside the project's root directory +- _optional:_ create & activate new virtual environment: + + === "*unix" + ```bash + python3 -m venv env + . ./env/bin/activate + ``` + + === "Windows" + === "CMD" + ```cmd + python -m venv env + env\scripts\activate.bat + ``` + === "Power Shell" + !!! attention "execution policy" + You may have to first set the correct execution policy, + before able to run the activation script. + + ```powershell + Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser + ``` + + ```powershell + python -m venv env + env\scripts\Activate.ps1 + ``` + +- install all required packages: + ``` + pip install -Ur requirements.txt + ``` + +### Usage + +To work on the documentation, the mkdocs development server has to run. +On start it tells you on which port it runs (default is `8000`). + +Open the Browser on the shown URL and edit the Markdown files. +On saving changes your Browser should automatically reload the page. + +- _optional:_ enter python virtual environment + + === "*unix" + ```bash + . ./env/bin/activate + ``` + + === "Windows" + === "CMD" + ```cmd + env\scripts\activate.bat + ``` + === "Power Shell" + !!! attention "execution policy" + You may have to first set the correct execution policy, + before able to run the activation script. + + ```powershell + Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser + ``` + + ```powershell + env\scripts\Activate.ps1 + ``` + +- start MkDocs development server: + ```bash + mkdocs serve + ``` +- work +- kill dev server by pressing `ctrl+c` +- _optional:_ exit python virtual environment: + ```bash + deactivate + ``` + +### Editor/IDE + +You don't need any special IDE, as a bare minimum a text editor would work (even vim is possible). +__But don't you dare to use this crappy Microsoft built in editor!__ + +Practically it's very supportive of course, +to use a IDE that has good markdown support in terms of code-highlighting, +table formatting, etc. +Below are collected tips for different IDE's. + +=== "VSCode" + recommended extensions: + _these are the extension id's searchable from vscode_ + + - `editorconfig.editorconfig` + - `waderyan.gitblame` + - `yzhang.markdown-all-in-one` + - `jebbs.plantuml` + +[gitscm-win]: https://git-scm.com/download/win +[java-net]: https://jdk.java.net/ +[maven-dl]: https://maven.apache.org/download.cgi +[python-win-dl]: https://www.python.org/downloads/windows/ diff --git a/mkdocs.yml b/mkdocs.yml index 9d4f619..2d458c4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -28,7 +28,7 @@ nav: - Ticket: 'api/systems/gitlab/ticket.md' - Ticketsystem: 'api/systems/gitlab/ticket-system.md' - Developers Guide: - - Index: 'developers-guide/index.md' + - Machine Setup: 'developers-guide/machine-setup.md' - Styleguide: 'developers-guide/styleguide.md' - Workflow: 'developers-guide/workflow.md' -- GitLab From 405d1586221b4588584765ee3a8d724cd64db278 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Wed, 2 Dec 2020 15:06:49 +0100 Subject: [PATCH 39/42] refactor(docs): index: change where to find machine setup --- docs/index.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index f45076a..14ae6b6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -29,7 +29,6 @@ Following is a list, what each site contains: - __Changelog:__ auto-generated changelog from the commits - __Contributing:__ - Prerequisites to be able to be a contributor to this project - - Needed machine-setup to develop (both for the library and documentation part) - __License:__ GNU GPLv3 content - __Usage:__ - needed entries to get this library into your own maven-project @@ -39,7 +38,7 @@ The __API__ part holds a detailed description, for each publicly accessible clas There is an own index file, explaining the package structure of the library and how it is documented. -The __Developers Guide__ is the part, you have to lookup the conventions and workflows used in this project, +The __Developers Guide__ is the part, you have to lookup how to setup your machine and conventions and workflows used in this project, if you decide to contribute to it. ## Maintainer -- GitLab From e870b2f88e872168dc7e2b815d7a84bd187a55b5 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Wed, 2 Dec 2020 15:28:07 +0100 Subject: [PATCH 40/42] refactor(docs): home: write contributing --- docs/unified-ticketing/contributing.md | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/docs/unified-ticketing/contributing.md b/docs/unified-ticketing/contributing.md index 9e5f0f6..ccdc25e 100644 --- a/docs/unified-ticketing/contributing.md +++ b/docs/unified-ticketing/contributing.md @@ -1,5 +1,19 @@ # Contributing -!!! todo - - Write Basic stuff a contributor needs to full-fill & know - - link to the Developers Guide found in top-bar +To contribute to this project, +you primarily have to be a member of the University of Applied Sciences Stuttgart. +This project is hosted on our Transferportal's GitLab instance, +to which only HFT members have access to my knowledge. + +Apart from that, for contributing to the library code itself, +you should be able to program Java and be familiar with maven. +For the documentation you need to have Python installed and know how to write Markdown. + +For all contributions you need to use Git. + +For details see the [Developer Guide][dev-guide]. +There you can find information about getting ready, +what rules to follow +and more developers than user based documentation about the library. + +[dev-guide]: ../developers-guide/machine-setup.md -- GitLab From ad4cc3665a8e2e1cf9b5ba37a0dffa054eabd035 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Wed, 2 Dec 2020 23:31:21 +0100 Subject: [PATCH 41/42] refactor(docs): dev-guide: remove obsolete index.md --- docs/developers-guide/index.md | 8 -------- 1 file changed, 8 deletions(-) delete mode 100644 docs/developers-guide/index.md diff --git a/docs/developers-guide/index.md b/docs/developers-guide/index.md deleted file mode 100644 index 1dca947..0000000 --- a/docs/developers-guide/index.md +++ /dev/null @@ -1,8 +0,0 @@ -# Developers Guide - -!!! todo - - small styleguide per used language - - need for unittests - - where to put what kind of class(core/systems package) - - how to commit (conventional changelog) - - GitLab workflow -- GitLab From c4430fdaab1a1e2ba581a46904cb6d37d1e9d8c8 Mon Sep 17 00:00:00 2001 From: 9Lukas5 Date: Wed, 2 Dec 2020 23:33:40 +0100 Subject: [PATCH 42/42] refactor(docs): dev-guide: write uml --- docs/developers-guide/uml.md | 411 +++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 412 insertions(+) create mode 100644 docs/developers-guide/uml.md diff --git a/docs/developers-guide/uml.md b/docs/developers-guide/uml.md new file mode 100644 index 0000000..c3666ae --- /dev/null +++ b/docs/developers-guide/uml.md @@ -0,0 +1,411 @@ +# Library UML-Diagram + +This is the full UML-diagram for the Unified-Ticketing library. + +!!! tip + You most likely can't read anything embedded to the site, + please open the graphics-URL in an extra tab and zoom in. + +```plantuml + +abstract Filter { + __ generics definition __ + T extends Ticket + F extends Filter + == + - {static} logger: Logger + + # {static} addToSet(\n\tfilterName: FilterNames,\n\tmap: Map,\n\tnewValue: String\n) + + __ instance definition __ + # setFilters: Map + + + constructor() + + + withAssigneeId(id: String): F + + withAssigneeName(name: String): F + + withDescriptionContain(substring: String): F + + withDescriptionMatch(regex: String): F + + withId(id: string): F + + isOpen(): F + + isClosed(): F + + withLabel(label: String): F + + setPage(page: int): F + + setPageSize(size: int): F + + withTitleContain(substring: String): F + + withTitleMatch(regex: String): F + + + {abstract} get(): List +} + +enum FilterNames { + + ASSIGNEEID + + ASSIGNEENAME + + DESCRIPTION_CONTAIN + + DESCRIPTION_MATCH + + IDS + + LABELS + + OPEN + + PAGE + + PAGINATION + + TITLE_CONTAINS + + TITLE_MATCH +} + +class Logging { + - {static} handler: Handler + - {static} mainLogger: Logger + - {static} logger: Logger + + + {static} getLogger(name: String): Logger + + {static} setFormatter(formatter: Formatter): void + + {static} setLevel(level: Level): void + + {static} test(message: String): void +} + +class RegisteredSystems <<(S, orange)>> { + - {static} logger: Logger + - {static} instance: RegisteredSystems + + # {static} getInstance(): RegisteredSystems + + __ instance definition __ + + constructor() + + + gitlab(): GitlabTicketSystemBuilder +} + +abstract Ticket { + __ generics definition __ + T \t extends Ticket + TS \t extends TicketSystem + == + - {static} logger: Logger + + __ instance definition __ + # assignees: Set + # description: String + # id: String + # labels: Set + # open: boolean + # title: String + + # updatedFields: Set + # parent: TS + + # constructor(parent: TS) + + + getAssignees(): Set + + {abstract} addAssignee(identifier: String): T + + clearAssignees(): T + + {asbtract} removeAssignee(identifier: String): T + + getDescription(): String + + setDescription(description: String): T + + getId(): String + + addLabel(label: String): T + + getLabels(): Set + + setLabels(labels: Set): T + + setLabels(labels: String[]): T + + isOpen(): boolean + + open(): T + + close(): T + + getParent(): TS + + getTitle(): String + + setTitle(title: String): T + + + {abstract} save(): T + + + equals(o: Object): boolean + + hashCode(): int + + toString(): String +} + +enum FieldNames { + + ASSIGNEES + + DESCRIPTION + + ID + + LABELS + + OPEN + + TITLE +} + +abstract TicketAssignee { + + email: String + + id: String + + fullName: String + + username: String + + # constructor(\n\temail: String,\n\tid: String,\n\tusername: String,\n\tfullName: String\n) + + + equals(o: Object): boolean + + hashCode(): int + + toString(): String +} + +abstract TicketBuilder { + __ generics definition __ + B \t extends TicketBuilder + T \t extends Ticket + TS \t extends TicketSystem + == + - {static} logger: Logger + + __ instance definition __ + # assignees: Set + # description: String + # labels: Set + # title: String + + # constructor(parent: TS) + + + assignees(identifiers: String...): B + + description(description: String): B + + labels(labels: Set): B + + labels(labels: String[]): B + + title(title: String): B + + + {abstract} create(): T +} + +abstract TicketSystem { + __ generics definition __ + B \t extends TicketBuilder + F \t extends Filter + T \t extends Ticket + TS \t extends TicketSystem + == + - {static} logger: Logger + + + {static} fromBuilder(): RegisteredSystems + + {static} fromUri(uri: String): TicketSystem + + __ instance definition __ + + apiKey: String + + baseUrl: String + + password: String + + username: String + + # configuration: Map + + + constructor() + + + config(option: ConfigurationOptions, value: String): TS + + config(option: ConfigurationOptions, value: boolean): TS + + getConfigTrue(option: ConfigurationOptions): boolean + + getConfigValue(option: ConfigurationOptions): Object + + {abstract} createTicket(): TB + + {abstract} find(): F + + {abstract} getTicketById(id: String): T + + {abstract} getTicketById(id: int): T + + + {abstract} hasAssigneeSupport(): boolean + + {abstract} hasDefaultPagination(): boolean + + {abstract} hasLabelSupport(): boolean + + {abstract} hasPaginationSupport(): boolean + + {abstract} hasReturnNullOnErrorSupport(): boolean +} + +enum ConfigurationOptions { + + RETURN_NULL_ON_ERROR +} + +abstract TicketSystemBuilder { + __ generics definition __ + B \t extends TicketBuilder + TS \t extends TicketSystem + == + - {static} logger: Logger + + __ instance definition __ + + baseUrl: String + + + withBaseUrl(url: String): B + + + {abstract} build(): TS +} + +' package connections +Filter *-- FilterNames: "inner class" +TicketSystem --> RegisteredSystems: "fromBuilder()" +TicketSystem *-- ConfigurationOptions: "inner class" +Ticket *-- FieldNames: "inner class" +Ticket --> Ticket: "save()" +Ticket o-- TicketSystem: "parent" +Ticket o-- TicketAssignee +TicketSystem --> TicketBuilder: "createTicket()" +TicketBuilder --> Ticket: "create()" + +class AssertionException { + + constructor() + + constructor(msg: String) + + constructor(msg: String, cause: Throwable) + + constructor(suppressed: Throwable) +} + +class DeserializationException { + + constructor() + + constructor(msg: String) + + constructor(msg: String, cause: Throwable) + + constructor(suppressed: Throwable) +} + +class HttpRequestException { + + constructor() + + constructor(msg: String) + + constructor(msg: String, cause: Throwable) + + constructor(suppressed: Throwable) +} + +class HttpResponseException { + + constructor() + + constructor(msg: String) + + constructor(msg: String, cause: Throwable) + + constructor(suppressed: Throwable) +} + +class SerializationException { + + constructor() + + constructor(msg: String) + + constructor(msg: String, cause: Throwable) + + constructor(suppressed: Throwable) +} + +class UnifiedticketingException { + + constructor() + + constructor(msg: String) + + constructor(msg: String, cause: Throwable) + + constructor(suppressed: Throwable) +} + +class UnsupportedFunctionException { + + constructor() + + constructor(msg: String) + + constructor(msg: String, cause: Throwable) + + constructor(suppressed: Throwable) +} + +AssertionException -[hidden]down- DeserializationException +DeserializationException -[hidden]down- HttpRequestException +HttpRequestException -[hidden]down- HttpResponseException +HttpResponseException -[hidden]down- SerializationException +SerializationException -[hidden]down- UnifiedticketingException +UnifiedticketingException -[hidden]down- UnsupportedFunctionException + +class GitlabFilter { + - {static} logger: Logger + + __ instance definition __ + # parent: GitlabTicketSystem + + # getHttpClient(): OkHttpClient + + get(): List +} + +class GitlabTicket { + - {static} logger: Logger + + # {static} fromTicketResponse(\n\tparent: GitlabTicketSystem,\n\tresponse: GitlabTicketResponse\n): GitlabTicket + + __ instance definition __ + # constructor(parent: GitLabTicketSystem) + + + addAssignee(userId: String): GitlabTicket + + addAssignee(userId: int): GitlabTicket + + removeAssignee(userId: String): GitlabTicket + + removeAssignee(userId: int): GitlabTicket + + save(): GitlabTicket + + + deepEquals(o: Object): boolean +} + +class GitlabTicketAssignee { + # constructor(id: int, fullName: String, username: String) +} + +class GitlabTicketBuilder { + - {static} logger: Logger + + __ instant definition __ + # constructor(parent: GitlabTicketSystem) + + + assignees(identifiers: String...): GitlabTicketBuilder + + assignees(identifiers: int...): GitlabTicketBuilder + + # getHttpClient(): OkHttpClient + + create(): GitlabTicket +} + +class GitlabTicketResponse { + + assignees: List + + description: String + + iid: int + + labels: Set + + state: String + + title: String + + # constructor() +} + +class Assignee { + + id: int + + name: String + + username: String +} + +class GitlabTicketSystem { + - {static} logger: Logger + + + {static} fromUri(uri: String): GitlabTicketSystem + + __ instance definition __ + # constructor() + + createTicket(): GitlabTicketBuilder + + find(): GitlabFilter + + getTicketById(id: String): GitlabTicket + + + hasAssigneeSupport(): boolean + + hasDefaultPagination(): boolean + + hasLabelSupport(): boolean + + hasPaginationSupport(): boolean + + hasReturnNullOnErrorSupport(): boolean +} + +class GitlabTicketSystemBuilder { + - {static} logger: Logger + + __ instance definition __ + # apiKey: String + # apiVersion: String + # projectId: int + # https: boolean + + + constructor() + + + withApiKey(apiKey: String): GitlabTicketSystemBuilder + + withHttp(): GitlabTicketSystemBuilder + + withHttps(): GitlabTicketSystemBuilder + + withProjectId(projectId: int): GitlabTicketSystemBuilder + + withProjectId(projectId: String): GitlabTicketSystemBuilder + + + build(): GitlabTicketSystem +} + +' package connections +GitlabFilter o-- GitlabTicketSystem: "parent" +GitlabTicketResponse o- Assignee: "inner class" +GitlabTicketSystemBuilder --> GitlabTicketSystem: "build()" +GitlabTicketSystem --> GitlabTicketBuilder: "createTicket()" +GitlabTicketBuilder --> GitlabTicket: "create()" +GitlabTicketSystem *-- GitlabTicketResponse + +' core package connections +GitlabFilter --|> Filter +GitlabTicket --|> Ticket +GitlabTicketAssignee --|> TicketAssignee +GitlabTicketBuilder --|> TicketBuilder +GitlabTicketSystem --|> TicketSystem +GitlabTicketSystemBuilder --|> TicketSystemBuilder + +RegisteredSystems --> GitlabTicketSystemBuilder: "gitlab()" + +``` diff --git a/mkdocs.yml b/mkdocs.yml index 2d458c4..e3df64a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -30,6 +30,7 @@ nav: - Developers Guide: - Machine Setup: 'developers-guide/machine-setup.md' - Styleguide: 'developers-guide/styleguide.md' + - UML Diagram: 'developers-guide/uml.md' - Workflow: 'developers-guide/workflow.md' theme: -- GitLab