Add collaborators

features/resources/_index.md

@@ -9,6 +9,30 @@ geekdocFilePath: _index.md
 
 ## Requirements
 
+### Accessing a resource as a collaborator
+
+{{< include file="features/resources/accessing_a_resource_as_a_collaborator.feature" language="gherkin" >}}
+
+### Being added/removed as a collaborator to/from a resource
+
+{{< include file="features/resources/being_added_removed_as_a_collaborator_to_from_a_resource.feature" language="gherkin" >}}
+
+### Pending Shares
+
+- As a user I don't want that resources I'm added as a collaborator to are directly available in my hierarchy and for sync for that I can decide whether I need them or not.
+- As a user I want that resources I'm added as a collaborator to are directly available in my hierarchy and for sync for that I can directly work with them without requiring any interaction.
+
+{{< include file="features/resources/pending_shares.feature" language="gherkin" >}}
+
+### Overview of received shared resources
+
+- As a user I only want to view the resources that I'm a collaborator of to separate other users' files from mine as well as to add or remove them to/from my personal space.
+- As a user I want to get a list of collaborator invitations that I didn't yet decide upon ("Pending Shares") to be able to add a resource to my personal space after dismissing the invitation notification or to re-add a resource I previously removed from my personal space.
+- As a user it helps me to list shares with state "Pending" first by default as these are usually the most actionable ones.
+- As a user I want to remove a shared resource from my personal space if I do no longer need it or accidentally accepted it in order to move it out of sight and to keep my account clean. The resource should stay shared with me but in a declined state. I don't want to inform the owner of the resource about it because I can restore access to the resource at any time by adding it again.
+
+{{< include file="features/resources/overview_of_received_shared_resources.feature" language="gherkin" >}}
+
 ### Accessing a resource via a link
 
 {{< include file="features/resources/accessing_a_resource_via_link.feature" language="gherkin" >}}

features/resources/accessing_a_resource_as_a_collaborator.feature

@@ -0,0 +1,70 @@
+Feature: Accessing a resource as a collaborator
+
+Scenario: Accessing a resource as a collaborator with the 'Viewer' role
+  GIVEN I'm a logged in user who is a collaborator of a resource
+    AND I have the role 'Viewer'
+#    AND I have added the resource to my personal space as in 'Feature: Overview of received shared resources' / 'Feature: Pending Shares'
+   WHEN accessing this resource
+   THEN I can list the resource and its contents
+    AND I can download the resource and its contents
+    AND I can view the resource and its contents as in 'Feature: Accessing a resource'
+    AND I can rename the resource as in 'Scenario: Renaming a shared resource in a user's personal space'
+    AND I can move the resource as in 'Scenario: Moving a shared resource within a user's personal space'
+    AND I can remove the resource from my personal space as in 'Feature: Removing a shared resource from a user's personal space'
+
+Scenario: Accessing a resource as a collaborator with the 'Editor' role
+  GIVEN I'm a logged in user who is a collaborator of a resource
+    AND I have the role 'Editor'
+#    AND I have added the resource to my personal space as in 'Feature: Overview of received shared resources' / 'Feature: Pending Shares'
+   WHEN accessing this resource
+   THEN I can list the resource and its contents
+    AND I can download the resource and its contents
+    AND I can view the resource and its contents as in 'Feature: Accessing a resource'
+    AND I can rename the resource as in 'Scenario: Renaming a shared resource in a user's personal space'
+    AND I can move the resource as in 'Scenario: Moving a shared resource within a user's personal space'
+    AND I can remove the resource from my personal space as in 'Feature: Removing a shared resource from a user's personal space'
+    AND I can rename the contents of the resource as in 'Feature: Renaming a resource'
+    AND I can delete the contents of the resource as in 'Feature: Deleting a resource'
+    AND I can move the contents of the resource as in 'Feature: Moving a resource'
+    AND I can move resources into the resource as in 'Feature: Moving a resource'
+    AND I can move resources out of the resource as in 'Feature: Moving a resource'
+    AND I can create resources within the resource as in 'Feature: Creating a resource'
+    AND I can upload resources into the resource as in 'Feature: Uploading a resource'
+    AND I can edit/change/update the resource and its contents
+
+Scenario: Accessing a resource as a collaborator with the 'Advanced permissions' role
+  GIVEN I'm a logged in user who is a collaborator of a resource
+    AND I have the role 'Advanced permissions'
+#    AND I have added the resource to my personal space as in 'Feature: Overview of received shared resources' / 'Feature: Pending Shares'
+   WHEN accessing this resource
+   THEN I can list the resource and its contents
+    AND I can download the resource and its contents
+    AND I can view the resource and its contents as in 'Feature: Accessing a resource'
+    AND I can rename the resource as in 'Scenario: Renaming a shared resource in a user's personal space'
+    AND I can move the resource as in 'Scenario: Moving a shared resource within a user's personal space'
+    AND I can remove the resource from my personal space as in 'Feature: Removing a shared resource from a user's personal space'
+    AND I can use the resource based on the additionally granted detailed permissions described below
+    AND the granted detailed permissions can stack/complement each other
+
+   WHEN accessing this resources without any of the detailed permissions
+   THEN the behavior equals 'Scenario: Accessing a resource as a collaborator with the 'Viewer' role'
+
+   WHEN accessing this resource only with the permission "Edit" (single file)
+   THEN I can edit/change/update the resource
+
+   WHEN accessing this resource only with the permission "Create" (folder)
+   THEN I can move resources into the resource as in 'Feature: Moving a resource'
+    AND I can create resources within the resource as in 'Feature: Creating a resource'
+    AND I can upload resources into the resource as in 'Feature: Uploading a resource'
+
+   WHEN accessing this resource only with the permission "Change" (folder)
+   THEN I can rename the contents of the resource as in 'Feature: Renaming a resource'
+    AND I can edit/change/update the resource and its contents
+
+   WHEN accessing this resource only with the permission "Delete" (folder)
+   THEN I can delete the contents of the resource as in 'Feature: Deleting a resource'
+    AND I can move resources out of the resource as in 'Feature: Moving a resource'
+
+   WHEN accessing this resource only with the permission "Manage"
+   THEN I can add collaborators to the resource as in 'Feature: Adding collaborators to a resource'
+    AND I can manage the collaborators of the resource as in 'Feature: Managing collaborators of a resource'

features/resources/being_added_removed_as_a_collaborator_to_from_a_resource.feature

@@ -0,0 +1,14 @@
+Feature: Being added/removed as a collaborator to/from a resource
+
+Scenario: Being added as a regular single user
+  GIVEN I'm a regular ownCloud user of the instance the resource is located on
+   WHEN I'm added as a collaborator to a resource as in 'Feature: Adding collaborators to a resource'
+   THEN the subsequent behavior is determined by 'Feature: Pending Shares'
+
+Scenario: Being removed as a collaborator from a resource
+  GIVEN I'm a collaborator of a certain resource
+   WHEN an Owner removes me from the resource as in 'Scenario: Removing a collaborator from a resource'
+     OR a Co-Owner removes me from the resource as in 'Scenario: Removing a collaborator from a resource'
+   THEN I do not have access to the resource anymore
+    AND the resource disappears from my resource list
+    AND I don't have a way to get back access except asking an Owner/Co-Owner to add me again

features/resources/overview_of_received_shared_resources.feature

@@ -0,0 +1,33 @@
+Feature: Overview of received shared resources
+
+Scenario: Listing received shared resources
+  GIVEN I'm logged in as a user
+   WHEN I have accepted collaborator invites
+     OR I have pending collaborator invites as in 'Scenario: Being added as a collaborator to a resource (Pending Shares enabled)'
+     OR I have shared resources that I removed from my personal space previously as in 'Feature: Removing a shared resource from a user's personal space'
+   THEN I can list these resources
+    AND I see the name of the resources
+    AND I see file type icons or thumbnails
+    AND I can recognize the initiator of the invite
+    AND I see the time since the invite has been initiated
+    AND I see the state of the invite (accepted/pending/declined)
+    AND I can add these resources to my personal space as in 'Scenario: Adding a shared resource to a user's personal space'
+    AND I can remove these resources from my personal space as in 'Scenario: Removing a shared resource from a user's personal space'
+    AND I can sort the list (ascending/descending) by name, state and time
+
+Scenario: Adding a shared resource to a user's personal space
+  GIVEN I'm a logged in user
+   WHEN I have pending collaborator invites as in 'Scenario: Being added as a collaborator to a resource (Pending Shares enabled)'
+     OR I have declined collaborator invites
+   THEN I can add such a resource to my personal space
+    AND the state of the invite changes to 'accepted'
+    AND the resource is located in the folder configured via the 'share_folder' option
+    AND I can access it as in 'Feature: Accessing a resource as a collaborator'
+
+Scenario: Removing a shared resource from a user's personal space
+  GIVEN I'm a logged in user
+   WHEN I have accepted collaborator invites
+   THEN I can remove such a resource from my personal space
+    AND the state of the invite changes to 'declined'
+    AND the resource is not located in my hierarchy any more
+    AND I can't access it any more

features/resources/pending_shares.feature

@@ -0,0 +1,16 @@
+Feature: Pending Shares
+
+Scenario: Being added as a collaborator to a resource (Pending Shares enabled)
+  GIVEN I'm added as a collaborator to a resource as in 'Feature: Adding collaborators to a resource'
+#   WHEN the option 'Automatically accept new incoming local user shares' is disabled
+   THEN the resource is not yet located in my file hierarchy
+#   THEN I am notified about the invite and can choose to 'accept' or 'decline' it
+    AND the resource appears in 'Feature: Overview of received shared resources' with state 'Pending'
+   WHEN I decline the resource
+#   THEN the notification is dismissed
+   THEN the state of the invite changes to 'declined'
+   WHEN I accept the resource
+#   THEN the notification is dismissed
+   THEN the state of the invite changes to 'accepted'
+    AND the resource is located in the folder configured via the 'share_folder' option
+    AND I can access it as in 'Feature: Accessing a resource as a collaborator'

features/sharing/_index.md

@@ -2,7 +2,7 @@
 title: Sharing
 geekdocRepo: https://github.com/owncloud/product
 geekdocEditPath: edit/master/docs
-geekdocFilePath: sharing.md
+geekdocFilePath: _index.md
 ---
 
 Sharing.

features/sharing/adding_collaborators_to_a_resource.feature

@@ -0,0 +1,25 @@
+Feature: Adding collaborators to a resource
+
+Scenario: Finding collaborators
+  GIVEN I'm a logged in user located in the collaborators panel of a resource
+   WHEN I start typing in the collaborator search field
+   THEN I see suggestions (with potentially many characters) based on the available user and group identifiers/attributes, sharing restrictions and options for autocomplete results. These are structured in the following way:
+        - [Avatar] Identifier / name / mail address / federation ID
+        - Additional information if applicable (e.g. 'Scenario: Extra field to display in autocomplete results')
+        - Type (User/Group/Guest/Federated)
+    AND the suggestions for guests or federated users only appear once I enter a compliant identifier (e.g., "[email protected]")
+   THEN I choose a collaborator
+    AND the chosen collaborator's becomes fixed but can easily be removed again
+    AND I can start typing again to add additional collaborators
+
+Scenario: Setting collaborator properties
+  GIVEN I'm adding collaborators as in 'Scenario: Finding collaborators'
+   WHEN having added the first collaborator
+   THEN I can choose a role for the chosen collaborators as in 'Feature: Roles for collaborators'
+   THEN I can set an expiration date for the chosen collaborators as in 'Feature: Expiration date for collaborators'
+
+Scenario: Confirming collaborators
+  GIVEN I have set collaborator properties as in 'Scenario: Setting collaborator properties'
+   WHEN I confirm the supplied information
+   THEN the collaborators are added to the resource according to the specified properties
+    AND I get visual feedback to know whether the action was successful or not

features/sharing/collaborators.md

@@ -0,0 +1,31 @@
+---
+title: Collaborators
+geekdocRepo: https://github.com/owncloud/product
+geekdocEditPath: edit/master/docs
+geekdocFilePath: collaborators.md
+---
+
+This document describes the features around 'Collaborators' from the perspective of the owner. The perspective of a recipient is described in the section 'Resources'.
+
+## User stories
+
+1. Adding single collaborators to a resource (user share)
+* Use case: As a user I want to exchange data with internal single users for that they get access and can collaborate with me
+
+## Requirements
+
+### Adding collaborators to a resource
+
+- As an owner or co-owner of a resource I want to be able to add other collaborators to the resource in order to provide access and to enable collaboration on the resource.
+
+{{< include file="features/sharing/adding_collaborators_to_a_resource.feature" language="gherkin">}}
+
+### Managing collaborators of a resource
+
+{{< include file="features/sharing/managing_collaborators_of_a_resource.feature" language="gherkin">}}
+
+### Roles for collaborators
+
+- As a regular user adding collaborators to a resource I want to choose roles for collaborators as these are easy to understand and less technical than raw permissions. Still, I need a brief explanation of what the roles exactly stand for in order to prevent mistakes. For legacy reasons and as a power user I still need granular permissions to restrict collaborators to exactly the features I want to allow.
+
+{{< include file="features/sharing/roles_for_collaborators.feature" language="gherkin">}}

features/sharing/managing_collaborators_of_a_resource.feature

@@ -0,0 +1,59 @@
+Feature: Managing collaborators of a resource
+
+Scenario: Viewing collaborators of a resource as an Owner/Co-Owner
+  GIVEN I'm a collaborator of a specific resource
+    AND I have the role 'Owner'
+#     OR I have the role 'Co-Owner'
+   WHEN looking at the resource in detail
+   THEN I get a list of all collaborators of the resource separated by users and groups whereby each entry contains the following information
+    - Name
+#    - Additional information based on 'Scenario: Extra field to display in autocomplete results'
+    - Avatar
+#    - Type (User/Guest/Federated)
+    - Role
+#    - State (pending/accepted; for local/federated/guest)
+#    - Expiration date (if applicable)
+    - Initiator of a reshare (if applicable)
+    AND I see the Owner of the resource always as the first entry in the list
+    AND I see myself in the list (if applicable)
+
+Scenario: Viewing collaborators of a resource as a regular collaborator
+  GIVEN I'm a collaborator of a specific resource
+    AND I don't have the role 'Owner'
+#    AND I don't have the role 'Co-Owner'
+   WHEN looking at the resource in detail
+   THEN I get a list of all collaborators whom I added to the resource, separated by users and groups whereby each entry contains the following information
+    - Name
+#    - Additional information based on 'Scenario: Extra field to display in autocomplete results'
+    - Avatar
+#    - Type (User/Guest/Federated)
+    - Role
+#    - State (pending/accepted; for local/federated/guest)
+#    - Expiration date (if applicable)
+    - Initiator of a reshare (if applicable)
+    AND I see the Owner of the resource always as the first entry in the list
+    AND I see myself in the list
+
+Scenario: Removing a collaborator from a resource
+  GIVEN I'm a collaborator of a specific resource
+    AND I have the role 'Owner'
+#     OR I have the role 'Co-Owner'
+     OR I have the permission 'Share'
+    AND I have previously added collaborators to the resource
+   WHEN looking at the resource in detail
+   THEN I can remove collaborators from the resource
+    AND I have to confirm the removal
+    AND the collaborator disappears from the list
+    AND the removed users do not have access anymore
+
+Scenario: Modifying a collaborator of a resource
+  GIVEN I'm a collaborator of a specific resource
+    AND I have the role 'Owner'
+#    OR I have the role 'Co-Owner'
+     OR I have the permission 'Share'
+    AND I have previously added collaborators to the resource
+   WHEN looking at the resource in detail
+   THEN I can change each collaborator's role as in 'Feature: Roles for collaborators'
+    AND I can change each collaborator's expiration date as in 'Feature: Expiration date for collaborators'
+    AND I have to confirm the modifications
+    AND the modifications take effect

features/sharing/roles_for_collaborators.feature

@@ -0,0 +1,50 @@
+Feature: Roles for collaborators
+
+- Owner: The physical owner of the resource
+#- Co-Owner: Full permissions including managing existing and adding additional collaborators
+- Editor: View + Edit permissions
+- Viewer: View only
+#- Dynamic roles (e.g. Secure Viewer)
+- Advanced permissions
+  - Cover legacy permission combinations
+  - Offer granular permission sets
+
+Scenario: Setting roles for collaborators on a single file
+  GIVEN I'm a collaborator of a specific file
+    AND I have the role 'Owner'
+#     OR I have the role 'Co-Owner'
+   WHEN located in 'Scenario: Setting collaborator properties'
+#   THEN I can choose the role 'Co-Owner'
+#    AND I see an explanatory note "Manage collaborators, view, download and edit"
+   THEN I can choose the role 'Editor'
+    AND I see an explanatory note "View, download and edit"
+   THEN I can choose the role 'Viewer'
+    AND I see an explanatory note "View and download"
+#   THEN I can choose dynamic roles like 'Secure Viewer' which are introduced by apps
+#    AND I see an explanatory note defined by the respective app
+#   WHEN choosing a dynamic role
+#   THEN I can set single sub-permissions like 'Print / Export PDF' defined by the respective app
+   THEN I can choose the role 'Advanced permissions'
+    AND I see an explanatory note "Set detailed permissions"
+   WHEN choosing the role 'Advanced permissions'
+   THEN I can set single permissions "Manage" and "Edit"
+
+Scenario: Setting roles for collaborators on a folder
+  GIVEN I'm a collaborator of a specific folder
+    AND I have the role 'Owner'
+#     OR I have the role 'Co-Owner'
+   WHEN located in 'Scenario: Setting collaborator properties'
+#   THEN I can choose the role 'Co-Owner'
+#    AND I see an explanatory note "Manage collaborators, view, download, edit and delete"
+   THEN I can choose the role 'Editor'
+    AND I see an explanatory note "View, download, edit and delete"
+   THEN I can choose the role 'Viewer'
+    AND I see an explanatory note "View and download"
+#   THEN I can choose dynamic roles like 'Secure Viewer' which are introduced by apps
+#    AND I see an explanatory note defined by the respective app
+#   WHEN choosing a dynamic role
+#   THEN I can set single sub-permissions like 'Print / Export PDF' defined by the respective app
+   THEN I can choose the role 'Advanced permissions'
+    AND I see an explanatory note "Set detailed permissions"
+   WHEN choosing the role 'Advanced permissions'
+   THEN I can set single permissions "Manage", "Create", "Change", "Delete"