Enhancement: Importing and Exporting

.gitignore

@@ -10,3 +10,71 @@ vendor/
 .php_cs.cache
 \.idea/
 settings.json
+
+### Claude Code ###
+CLAUDE.md
+claude.log
+
+# OS-Files
+# Created by https://www.toptal.com/developers/gitignore/api/windows,linux,visualstudiocode
+# Edit at https://www.toptal.com/developers/gitignore?templates=windows,linux,visualstudiocode
+### Linux ###
+*~
+
+# temporary files which can be created if a process still has a handle open of a deleted file
+.fuse_hidden*
+
+# KDE directory preferences
+.directory
+
+# Linux trash folder which might appear on any partition or disk
+.Trash-*
+
+# .nfs files are created when an open file is removed but is still being accessed
+.nfs*
+
+### VisualStudioCode ###
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+!.vscode/*.code-snippets
+
+# Local History for Visual Studio Code
+.history/
+
+# Built Visual Studio Code Extensions
+*.vsix
+
+### VisualStudioCode Patch ###
+# Ignore all local history of files
+.history
+.ionide
+
+### Windows ###
+# Windows thumbnail cache files
+Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+
+# Dump file
+*.stackdump
+
+# Folder config file
+[Dd]esktop.ini
+
+# Recycle Bin used on file shares
+$RECYCLE.BIN/
+
+# Windows Installer files
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+
+# Windows shortcuts
+*.lnk
+# End of https://www.toptal.com/developers/gitignore/api/linux,windows,visualstudiocode

docs/User_documentation_en.md

@@ -21,7 +21,7 @@ Overall, Deck is easy to use. You can create boards, add users, share the Deck,
 5. [Archive old tasks](#5-archive-old-tasks)
 6. [Manage your board](#6-manage-your-board)
 7. [Sharing boards](#7-sharing-boards)
-8. [Import boards](#8-import-boards)
+8. [Export and import boards](#8-export-and-import-boards)
 9. [Trello interoperability](#9-trello-interoperability)
 10. [Search](#10-search)
 11. [New owner for the deck entities](#11-new-owner-for-the-deck-entities)
@@ -95,11 +95,43 @@ If a user is member of one or several group(s) or circle(s) a board is shared wi
 1. If a user is namely specified in a board's acl, (s)he gets the permission assigned to her/him;
 2. Else, if a user is member of one or several circle(s) or group(s), (s)he gets the permission when at least one circle/group (s)he is member of has the permission.
 
-### 8. Import boards
+### 8. Export and import boards
 
-Importing can be done using the API or the `occ` `deck:import` command.
+#### Exporting a board
 
-Comments with more than 1000 characters are placed as attached files to the card.
+Open the board menu (**...**) and choose **Export board**. Two formats are offered:
+
+* **JSON** — a complete copy of the board. It contains the lists, all cards
+  including archived ones, their completion state and dates, tags, assigned
+  users, comments and the contents of file attachments. This is the format to
+  pick if you want to be able to import the board again later.
+* **CSV** — one row per card, for opening in a spreadsheet or feeding into a
+  reporting tool. It cannot be imported back into Deck.
+
+Attachments are embedded in the JSON file, which can make it large. If you do not
+need them, untick **Attachments** in the dialog — the export will then be smaller,
+but it will no longer restore the board completely. **Archived cards** and
+**Comments** can be left out in the same way.
+
+#### Importing a board
+
+Choose **Import board** in the left sidebar and select a JSON file that was
+exported from Deck. Before the import runs, a dialog lets you pick what to
+restore: cards, archived cards, completion state, due and start dates, tags,
+assigned users, comments, attachments and sharing.
+
+The lists and the tags of a board are always created. If you untick **Cards**,
+you therefore end up with an empty copy of the board, which is a convenient way
+to turn an existing board into a template.
+
+Two things are worth knowing about an import:
+
+* The board is created new and belongs to you, and its cards get new IDs.
+  References between cards, such as dependencies, are adjusted to the new cards.
+  A reference to a card that was not imported is dropped.
+* Attachments are placed in your own **Deck** folder in Files.
+
+Importing can also be done using the API or the `occ` `deck:import` command.
 
 It is possible to import from the following sources:
 

docs/export-import.md

@@ -4,21 +4,76 @@
 -->
 ## Export
 
-Deck currently supports exporting all boards a user owns in a single JSON file. The format is based on the database schema that Deck uses. It can be used to re-import boards on the same or other instances.
-
-The export currently has some known limitations in terms of specific data not included:
+Deck supports exporting boards to a single JSON file. The format is based on the database schema that Deck uses. It can be used to re-import boards on the same or other instances.
+
+The export is a complete representation of a board and contains:
+- lists, including which one is configured as the done column
+- cards, including archived ones, with their card ID and list ID
+- the completion state and the date a card was completed
+- due date, start date, creation date and last modification date
+- card colour and card type
+- dependencies between cards
+- labels, assigned users, comments and file attachments
+
+On import, card dependencies are remapped to the newly created cards. A
+dependency that points at a card outside the import - one on another board, or
+one skipped because archived cards were deselected - is dropped instead of
+leaving a dangling reference behind.
+
+Dates are exported as ISO 8601 including the UTC offset, so they keep pointing at
+the same point in time no matter which timezone imports or reads them.
+
+Known limitations, this data is not part of an export:
 - Activity information
-- File attachments to Deck cards
-- Comments
+- Cards in the trash bin
+
+### From the web interface
+
+Open the board menu, choose *Export board* and pick a format:
+
+- **JSON** – the complete board, suited for importing back into Deck.
+- **CSV** – one row per card with the card ID, list ID, list name, tags, assigned
+  users, archived and completion state, all date fields and the comment and
+  attachment counts. Suited for reporting and for external tools such as
+  spreadsheets or BI tools. A CSV cannot be imported back into Deck.
+
+The CSV follows RFC 4180: comma separated, every field quoted, inner quotes
+doubled, and UTF-8 with a byte order mark. A separator, a semicolon or the line
+breaks of a markdown description can therefore appear inside a cell without
+breaking the file.
+
+Exports are machine readable output, so nothing in them is translated. The column
+headers are always English and archived and completed are written as `1` and `0`,
+which means a report keeps working no matter which interface language the
+exporting user has. The JSON export behaves the same way, its keys being the
+English property names.
+
+Attachment contents are never part of a CSV, but the attachment count is, so the
+column stays meaningful.
+
+Attachment contents are embedded in the JSON export, which can make the file
+large. They can be left out in the export dialog, at the cost of an export that
+no longer restores the board completely.
+
+### From the command line
 
 ```
 occ deck:export userid > userid-deck-export.json
 ```
 *(`userid` = username as seen in the admin user accounts page)*
 
+Pass `--no-attachments` to leave the attachment contents out of the export.
+
 ## Import Boards
 
-Importing can be done using the API or the `occ` `deck:import` command.
+Importing can be done from the web interface, using the API or the `occ`
+`deck:import` command.
+
+When importing a board through the web interface, a dialog offers to select which
+parts of the file to restore: cards, archived cards, completion state, due and
+start dates, tags, assigned users, comments, attachments and sharing. Lists and
+labels are always created, so deselecting cards results in an empty copy of the
+board that can be used as a template.
 
 It is possible to import from the following sources:
 

docs/import-class-diagram.md

@@ -6,6 +6,6 @@
 
 Importing boards to the Deck implements the class diagram below.
 
-> **NOTE**: When making any changes to the structure of the classes or implementing import from other sources, edit the `BoardImport.yuml` file
+> **NOTE**: When making any changes to the structure of the classes or implementing import from other sources, edit the `BoardImport.yuml` file and regenerate `BoardImport.svg` from it with the [yUML extension](https://github.com/jaime-olivares/vscode-yuml).
 
 ![Screenshot](resources/BoardImport.svg)