Refine adrs

Signed-off-by: Jörn Friedrich Dreyer <[email protected]>
owncloud · Feb 16, 2021 · 93c8a2a · 93c8a2a
1 parent b8e18a8
commit 93c8a2a
Show file tree

Hide file tree

Showing 5 changed files with 64 additions and 27 deletions.
diff --git a/.adr-dir b/.adr-dir
@@ -0,0 +1 @@
+docs/ocis/adr
diff --git a/docs/adr/0001-introduce-accounts-service.md → ...is/adr/0001-introduce-accounts-service.md b/docs/adr/0001-introduce-accounts-service.md → ...is/adr/0001-introduce-accounts-service.md
@@ -1,16 +1,22 @@
-# 1. Introduce an accounts service
+---
+title: "1. Introduce an accounts service"
+date: 2020-06-15T20:21:00+01:00
+geekdocRepo: https://github.com/owncloud/ocis
+geekdocEditPath: edit/master/docs/ocis/adr
+geekdocFilePath: 0001-introduce-accounts-service.md
+---
 
-* Status: superseded by [ADR-0003](0003-external-user-management.md) <!-- optional -->
-* Deciders: @butonic, @felixboehm, @micbar, @pmaier1 <!-- optional -->
-* Date: [2020-06-15](https://github.com/owncloud/ocis-accounts/pull/34/commits/2fd05e2b6fe2a47c687bd0c0bc5e1b5c48a585b2) <!-- optional -->
+* Status: superseded by [ADR-0003]({{< ref "0003-external-user-management.md" >}})
+* Deciders: @butonic, @felixboehm, @micbar, @pmaier1
+* Date: [2020-06-15](https://github.com/owncloud/ocis-accounts/pull/34/commits/2fd05e2b6fe2a47c687bd0c0bc5e1b5c48a585b2)
 
-Technical Story: [persist accounts](https://github.com/owncloud/ocis-accounts/pull/34) <!-- optional -->
+Technical Story: [persist accounts](https://github.com/owncloud/ocis-accounts/pull/34)
 
 ## Context and Problem Statement
 
 To attach metadata like shares to users ownCloud relies on persistent, non-reassignable, unique identifiers for users (and files). Email und username can change when a user changes his name. But even the OIDC sub+iss combination may change when the IdP changes. While there is [an account porting protocol](https://openid.net/specs/openid-connect-account-porting-1_0.html) that describes how a relying party (RP) such as ownCloud should behave, it still requires the RP to maintain its own user identifiers.
 
-## Decision Drivers <!-- optional -->
+## Decision Drivers
 
 * oCIS should be a single binary that can run out of the box without external dependencies like an LDAP server.
 * Time: we want to build a release candidate asap.
@@ -27,16 +33,16 @@ To attach metadata like shares to users ownCloud relies on persistent, non-reass
 
 Chosen option: "GLAuth wraps accounts service", because we need write access to provision guest accounts and GLAuth currently has no write support.
 
-### Positive Consequences <!-- optional -->
+### Positive Consequences
 
 * We can build a self contained user management in the accounts service and can adjust it to our requirements.
 * We do not rely on an LDAP server which would only be possible by implementing write support in the LDAP libraries used by GLAuth (hard to estimate effort, when will that be merged upstream).
 
-### Negative Consequences <!-- optional -->
+### Negative Consequences
 
 * We need to spend time on implementing user management
 
-## Pros and Cons of the Options <!-- optional -->
+## Pros and Cons of the Options
 
 ### Accounts service wraps LDAP
 

diff --git a/...002-persist-accounts-using-cs3-storage.md → ...002-persist-accounts-using-cs3-storage.md b/...002-persist-accounts-using-cs3-storage.md → ...002-persist-accounts-using-cs3-storage.md
@@ -1,10 +1,16 @@
-# 2. Persist accounts in a CS3 storage
+---
+title: "2. Persist accounts in a CS3 storage"
+date: 2020-08-21T20:21:00+01:00
+geekdocRepo: https://github.com/owncloud/ocis
+geekdocEditPath: edit/master/docs/ocis/adr
+geekdocFilePath: 0002-persist-accounts-using-cs3-storage.md
+---
 
-* Status: accepted <!-- optional -->
-* Deciders: @butonic, @felixboehm <!-- optional -->
-* Date: 2020-08-21 <!-- optional -->
+* Status: accepted
+* Deciders: @butonic, @felixboehm
+* Date: 2020-08-21
 
-Technical Story: [File system based indexing](https://github.com/owncloud/ocis-accounts/pull/92) <!-- optional -->
+Technical Story: [File system based indexing](https://github.com/owncloud/ocis-accounts/pull/92)
 
 ## Context and Problem Statement
 
@@ -19,11 +25,11 @@ To set up High Availability (HA) or a geo-replicated setup we need to persist ac
 
 Chosen option: "Persist users in a CS3 storage", because we have one service less running and can rely on the filesystem for geo-replication and HA.
 
-### Positive Consequences <!-- optional -->
+### Positive Consequences
 
 * We can store accounts on the storage using the CS3 API, pushing geo-distribution to the storage layer.
 * Backups of users and storage can be implemented without inconsistencies between using snapshots.
 
-### Negative Consequences <!-- optional -->
+### Negative Consequences
 
 * We need to spend time on implementing a reverse index based on files, and symlinks.
diff --git a/docs/adr/0003-external-user-management.md → ...ocis/adr/0003-external-user-management.md b/docs/adr/0003-external-user-management.md → ...ocis/adr/0003-external-user-management.md
@@ -1,16 +1,22 @@
-# 3. Use external User Management
+---
+title: "3. Use external User Management"
+date: 2020-12-09T20:21:00+01:00
+geekdocRepo: https://github.com/owncloud/ocis
+geekdocEditPath: edit/master/docs/ocis/adr
+geekdocFilePath: 0003-external-user-management.md
+---
 
-* Status: accepted <!-- optional -->
-* Deciders: @butonic, @micbar, @dragotin, @hodyroff, @pmaier1 <!-- optional -->
-* Date: 2020-12-09 <!-- optional -->
+* Status: accepted
+* Deciders: @butonic, @micbar, @dragotin, @hodyroff, @pmaier1
+* Date: 2020-12-09
 
-Technical Story: [Skip account-service by talking to CS3 user-api](https://github.com/owncloud/ocis/pull/1020) <!-- optional -->
+Technical Story: [Skip account-service by talking to CS3 user-api](https://github.com/owncloud/ocis/pull/1020)
 
 ## Context and Problem Statement
 
 To attach metadata like shares to users ownCloud relies on persistent, non-reassignable, unique identifiers for users (and files). Email and username can change when a user changes his name. But even the OIDC sub+iss combination may change when the IdP changes. While there is [an account porting protocol](https://openid.net/specs/openid-connect-account-porting-1_0.html) that describes how a relying party (RP) such as ownCloud should behave, it still requires the RP to maintain its own user identifiers.
 
-## Decision Drivers <!-- optional -->
+## Decision Drivers
 
 * oCIS should be a single binary that can run out of the box without external dependencies like an LDAP server.
 * Time: we want to build a release candidate asap.
@@ -55,20 +61,20 @@ Chosen option: "Move accounts functionality to GLAuth and name it accounts", by
 - The current CS3 API for user management should be enriched with pagination, field mask and a query language as needed
 - properly register an [auxiliary LDAP schema that adds an ownCloudUUID attribute to users and groups](https://github.com/owncloud/ocis/blob/c8668e8cb171860c70fec29e5ae945bca44f1fb7/deployments/examples/cs3_users_ocis/config/ldap/ldif/10_owncloud_schema.ldif)
 
-### Positive Consequences <!-- optional -->
+### Positive Consequences
 
 * The accounts service (which is our drop in LDAP solution) can be dropped. The CS3 userprovider service becomes the only service dealing with users.
 * No sync
 
-### Negative Consequences <!-- optional -->
+### Negative Consequences
 
 * If users want to store users in their IDM and at the same time guests in a seperate user management we need to implement GLAuth backends that support more than one LDAP server.
 
-## Pros and Cons of the Options <!-- optional -->
+## Pros and Cons of the Options
 
 ### GLAuth wraps accounts service
 
-Currently, the accounts service is the source of truth and we use it to implement user management. <!-- optional -->
+Currently, the accounts service is the source of truth and we use it to implement user management.
 
 * Good, because it solves the problem of storing and looking up an owncloud UUID for a user (and group)
 * Good, because we can manage users out of the box
@@ -77,7 +83,7 @@ Currently, the accounts service is the source of truth and we use it to implemen
 
 ### Move accounts functionality to GLAuth and name it accounts
 
-We should use an existing LDAP server and make GLAuth a drop in replacement for it. <!-- optional -->
+We should use an existing LDAP server and make GLAuth a drop in replacement for it.
 
 * Good, because we can use an existing user repository (an LDAP server), no need to sync or learn users.
 * Good, because admins can rely on existing user management tools.
@@ -102,3 +108,6 @@ We should use an existing LDAP server and make GLAuth a drop in replacement for
 * Good, because we can use the CS3 user provider with the existing LDAP / rest driver.
 * Bad, because oCIS admins may not have the rights to manage role assignments. (But this is handled at a different department.) 
 * Bad, because oCIS admins may not have the rights to disable users if an external LDAP is used instead of the drop in GLAuth.
+
+## Links
+* supersedes [ADR-0001]({{< ref "0001-introduce-accounts-service.md" >}})
diff --git a/docs/ocis/adr/_index.md b/docs/ocis/adr/_index.md
@@ -0,0 +1,15 @@
+---
+title: "Architecture Decisions"
+date: 2021-02-10T20:21:00+01:00
+weight: 15
+geekdocRepo: https://github.com/owncloud/ocis
+geekdocEditPath: edit/master/docs/ocis/adr
+geekdocFilePath: _index.md
+geekdocCollapseSection: true
+---
+
+oCIS is documenting architecture decisions using [Markdown Architectural Decision Records](https://adr.github.io/madr/) (MADR), following [Documenting Architecture Decisions by Michael Nygard](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions).
+
+{{< toc >}}
+
+To manage the records we use [butonic/adr-tools](https://github.com/butonic/adr-tools), a fork of the original [npryce/adr-tools](https://github.com/npryce/adr-tools), based on [a pull request that should have added MADR support](https://github.com/npryce/adr-tools/pull/43). It also supports a YAML header that is used by our Hugo based doc generation