Merge branch '3-write-github-docs' into 'master'

Resolve "write github docs"

Closes #3

See merge request !3

docs/api/systems/github/ticket-system.md

+# GitHub-Ticketsystem
+
+This documents GitHub 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 `GithubTicketSystem` object is always referencing a specific GitHub project.
+Mandatory information to instantiate it, are the GitHub instances base url, the project owner and project.
+
+For public accessible actions, it can be used anonymously.
+Other operations have to be authenticated using an username and a personal access token.
+
+For all calls the `accept` header will be set to `application/vnd.github.v3+json`.
+If not configured otherwise, connections will use `https`.
+
+### by URI
+
+```java
+// recommended option
+GithubTicketSystem ts = (GithubTicketSystem) TicketSystem.fromUri("<uri>");
+
+// second possible declaration
+TicketSystem<
+    GithubTicket,
+    GithubTicketSystem,
+    GithubTicketBuilder,
+    GithubFilter
+    > gl = TicketSystem.fromUri("<uri>");
+```
+
+The first declaration option uses the child-class from the GitHub 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 GitHub no matter what.
+This way you can see GitHub 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:github:[http://|https://]<base url>::<owner>:<repo>[:<username>:<apikey>]
+```
+
+- protocol for http/https is optional. If not given, https is used
+- base url can contain also non-standard port hosted github instances
+- username and api key if authentication needed, otherwise anonymous access is used
+
+??? example "URI examples"
+    - non-https anonymous, owner me, project hello-world, public gitlab  
+        `unifiedticketing:github:http://api.github.com::me:hello-world`
+    - implicit https authenticated, owner me, project hello-world, public gitlab  
+        `unifiedticketing:github:api.github.com::me:hello-world:me:1234896102765abcddbda324bb3a3`
+    - explicit https authenticated, owner me, project hello-world, fictional github, non-standard port  
+        `unifiedticketing:github:https://api.github.example.org:8080::me:hello-world:me: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, owner me, repo hello-world, public github  
+        ```java
+        GithubTicketSystem ts = TicketSystem.fromBuilder()
+            .github()
+            .withBaseUrl("api.github.com")
+            .withHttp()
+            .withOwner("me")
+            .withRepo("hello-world")
+            .build();
+        ```
+    - implicit https authenticated, owner me, repo hello-world, public github  
+        ```java
+        GithubTicketSystem ts = TicketSystem.fromBuilder()
+            .github()
+            .withBaseUrl("api.github.com")
+            .withOwner("me")
+            .withRepo("hello-world")
+            .withAuthentication("me", "1234896102765abcddbda324bb3a3")
+            .build();
+        ```
+    - explicit https authenticated, owner me, repo hello-world, fictional github, non-standard port  
+        ```java
+        GithubTicketSystem ts = TicketSystem.fromBuilder()
+            .github()
+            .withBaseUrl("api.github.example.org:8080")
+            .withHttps()
+            .withOwner("me")
+            .withRepo("hello-world")
+            .withAuthentication("me", "1234896102765abcddbda324bb3a3")
+            .build();
+        ```
+
+## list tickets
+
+!!! warning "default pagination"
+    GitHub has a default pagination on _30_ elements per page.
+    Highest possible value is _100_ elements. [[Link]][api-docs-pagination]
+
+!!! info "assignees"
+    GitHub implementation supports the fields `id` and `username`.
+    If ticket has no assignees, assignee field stays `null`.
+
+From the filters shown on the global `TicketSystem` docs,
+the ones for title, description filter and ticket id's are not natively supported by the GitHub API.
+If such a filter is used,
+this get's done locally after receiving the response from GitHub,
+before handing it to the user.
+
+## get single ticket
+
+As the GitHub API doesn't support a ticket-id filter on the list endpoint,
+the method for getting a single ticket by it's id uses the single ticket endpoint.
+
+If you use the Filter class with a single ticket id as only filter,
+you end up fetching all tickets of that repo, filtering out all non matching ones locally.
+
+## create new ticket
+
+For a new GitHub ticket a title is mandatory.
+Everything else is optional.
+
+!!! example "minimal example"
+    ```java
+    GithubTicket = ts.createTicket()
+        .title("my new ticket")
+        .create();
+    ```
+
+Setting an assignee, has to be by user login name.
+
+[core-ts]: ../../core/ticket-system.md
+[api-docs-issues-list]: https://docs.github.com/en/free-pro-team@latest/rest/reference/issues#list-repository-issues
+[api-docs-pagination]: https://docs.github.com/en/free-pro-team@latest/rest/overview/resources-in-the-rest-api#pagination

docs/api/systems/github/ticket.md

+# GitHub-Ticket
+
+!!! todo
+    write usage api docs

docs/developers-guide/uml.md

@@ -8,6 +8,10 @@ This is the full UML-diagram for the Unified-Ticketing library.
 
 ```plantuml
 
+' ==========
+' Core
+' ==========
+
 abstract Filter {
     __ generics definition __
     T extends Ticket
@@ -235,6 +239,10 @@ Ticket o-- TicketAssignee
 TicketSystem --> TicketBuilder: "createTicket()"
 TicketBuilder --> Ticket: "create()"
 
+' ==========
+' Exceptions
+' ==========
+
 class AssertionException {
     + constructor()
     + constructor(msg: String)
@@ -291,6 +299,132 @@ HttpResponseException -[hidden]down- SerializationException
 SerializationException -[hidden]down- UnifiedticketingException
 UnifiedticketingException -[hidden]down- UnsupportedFunctionException
 
+' ==========
+' GitHub
+' ==========
+
+class GithubFilter {
+    - {static} logger: Logger
+
+    __ instance definition __
+    # parent: GithubTicketSystem
+
+    # getHttpClient(): OkHttpClient
+    + get(): List<GithubTicket>
+}
+
+class GithubTicket {
+    - {static} logger: Logger
+
+    # {static} fromTicketResponse(\n\tparent: GithubTicketSystem,\n\tresponse: GithubTicketResponse\n): GithubTicket
+
+    __ instance definition __
+    # constructor(parent: GithubTicketSystem)
+
+    + addAssignee(userId: String): GithubTicket
+    + removeAssignee(userId: String): GithubTicket
+    + save(): GithubTicket
+
+    + deepEquals(o: Object): boolean
+}
+
+class GithubTicketAssignee {
+    # constructor(id: int, username: String)
+}
+
+class GithubTicketBuilder {
+    - {static} logger: Logger
+
+    __ instant definition __
+    # constructor(parent: GithubTicketSystem)
+
+    # getHttpClient(): OkHttpClient
+    + create(): GitlabTicket
+}
+
+class GithubTicketResponse {
+    + assignees: Set<Assignee>
+    + body: String
+    + labels: Set<Label>
+    + number: int
+    + state: String
+    + title: String
+
+    # constructor()
+}
+
+class GithubTicketResponse.Assignee {
+    + number: int
+    + login: String
+}
+
+class GithubTicketResponse.Label {
+    + name: String
+}
+
+class GithubTicketSystem {
+    - {static} logger: Logger
+
+    + {static} fromUri(uri: String): GithubTicketSystem
+
+    __ instance definition __
+    # constructor()
+    + createTicket(): GithubTicketBuilder
+    + find(): GithubFilter
+    + getTicketById(id: String): GithubTicket
+
+    + hasAssigneeSupport(): boolean
+    + hasDefaultPagination(): boolean
+    + hasLabelSupport(): boolean
+    + hasPaginationSupport(): boolean
+    + hasReturnNullOnErrorSupport(): boolean
+}
+
+class GithubTicketSystemBuilder {
+    - {static} logger: Logger
+
+    __ instance definition __
+    # acceptHeader: String
+    # apiKey: String
+    # https: boolean
+    # owner: String
+    # repo: String
+    # username: String
+
+    + constructor()
+
+    + withAuthentication(username: String, apiKey: String): GithubTicketSystemBuilder
+    + withHttp(): GithubTicketSystemBuilder
+    + withHttps(): GithubTicketSystemBuilder
+    + withOwner(owner: String): GithubTicketSystemBuilder
+    + withRepo(repo: String): GithubTicketSystemBuilder
+
+    + build(): GithubTicketSystem
+}
+
+' package connections
+GithubFilter o-- GithubTicketSystem: "parent"
+GithubTicketResponse o- GithubTicketResponse.Assignee: "inner class"
+GithubTicketResponse o-down- GithubTicketResponse.Label: "inner class"
+GithubTicketSystemBuilder --> GithubTicketSystem: "build()"
+GithubTicketSystem --> GithubTicketBuilder: "createTicket()"
+GithubTicketBuilder --> GithubTicket: "create()"
+GithubTicketSystem *-- GithubTicketResponse
+
+' core package connections
+GithubFilter --|> Filter
+GithubTicket --|> Ticket
+GithubTicketAssignee --|> TicketAssignee
+GithubTicketBuilder --|> TicketBuilder
+GithubTicketSystem --|> TicketSystem
+GithubTicketSystemBuilder --|> TicketSystemBuilder
+
+RegisteredSystems --> GithubTicketSystemBuilder: "github()"
+
+' ==========
+' GitLab
+' ==========
+
 class GitlabFilter {
     - {static} logger: Logger
 
@@ -346,7 +480,7 @@ class GitlabTicketResponse {
     # constructor()
 }
 
-class Assignee {
+class GitlabTicketResponse.Assignee {
     + id: int
     + name: String
     + username: String
@@ -392,7 +526,7 @@ class GitlabTicketSystemBuilder {
 
 ' package connections
 GitlabFilter o-- GitlabTicketSystem: "parent"
-GitlabTicketResponse o- Assignee: "inner class"
+GitlabTicketResponse o- GitlabTicketResponse.Assignee: "inner class"
 GitlabTicketSystemBuilder --> GitlabTicketSystem: "build()"
 GitlabTicketSystem --> GitlabTicketBuilder: "createTicket()"
 GitlabTicketBuilder --> GitlabTicket: "create()"

docs/index.md

@@ -64,7 +64,7 @@ He is the current maintainer for this project and the appropriate contact for qu
 [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=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-latest-tag]: https://img.shields.io/badge/dynamic/json?color=success&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

mkdocs.yml

@@ -24,6 +24,9 @@ nav:
       - Ticketsystem: 'api/core/ticket-system.md'
     - Exceptions: 'api/exceptions.md'
     - Systems:
+        - GitHub:
+          - Ticket: 'api/systems/github/ticket.md'
+          - Ticketsystem: 'api/systems/github/ticket-system.md'
         - GitLab:
           - Ticket: 'api/systems/gitlab/ticket.md'
           - Ticketsystem: 'api/systems/gitlab/ticket-system.md'