From 6dda67702a74ab876ad44f3c1135d3eb4f2c28c8 Mon Sep 17 00:00:00 2001
From: lkassianik <lyubakassianik@gmail.com>
Date: Thu, 25 Jun 2015 14:10:19 -0700
Subject: [PATCH] Starting the Calendar user guide

Summary: Ref T7951, Starting the Calendar user guide

Test Plan: Go to {nav Diviner > Phabricator User Docs > Calendar User Guide}, read about how fabulous the Calendar application is.

Reviewers: epriestley, #blessed_reviewers

Reviewed By: epriestley, #blessed_reviewers

Subscribers: epriestley, Korvin

Maniphest Tasks: T7951

Differential Revision: https://secure.phabricator.com/D13496
---
 .../PhabricatorCalendarApplication.php        |  9 ++
 src/docs/user/userguide/calendar.diviner      | 83 +++++++++++++++++++
 2 files changed, 92 insertions(+)
 create mode 100644 src/docs/user/userguide/calendar.diviner

diff --git a/src/applications/calendar/application/PhabricatorCalendarApplication.php b/src/applications/calendar/application/PhabricatorCalendarApplication.php
index b5bdfaa1eb..0197ec8f02 100644
--- a/src/applications/calendar/application/PhabricatorCalendarApplication.php
+++ b/src/applications/calendar/application/PhabricatorCalendarApplication.php
@@ -68,6 +68,15 @@ final class PhabricatorCalendarApplication extends PhabricatorApplication {
     );
   }
 
+  public function getHelpDocumentationArticles(PhabricatorUser $viewer) {
+    return array(
+      array(
+        'name' => pht('Calendar User Guide'),
+        'href' => PhabricatorEnv::getDoclink('Calendar User Guide'),
+      ),
+    );
+  }
+
   public function getQuickCreateItems(PhabricatorUser $viewer) {
     $items = array();
 
diff --git a/src/docs/user/userguide/calendar.diviner b/src/docs/user/userguide/calendar.diviner
new file mode 100644
index 0000000000..e6f9bd4b2c
--- /dev/null
+++ b/src/docs/user/userguide/calendar.diviner
@@ -0,0 +1,83 @@
+@title Calendar User Guide
+@group userguide
+
+Guide to the Calendar application.
+
+Overview
+========
+
+IMPORTANT: Calendar is a prototype application. See
+@{article:User Guide: Prototype Applications}.
+
+The Calendar application is a tool that allows users to schedule group events
+and share personal plans.
+
+There are several kinds of events you can create:
+
+- Regular events such as a one-time meeting or a personal appointment.
+- All day events such as a company-wide holiday or a vacation.
+- Recurring events, which can be regular or all day, such as a weekly 1-1 or
+  a birthday.
+
+
+Editing Events
+==============
+
+All fields of basic and all day events can be edited after the event has been
+created.
+
+Every instance of a recurring event has an index that maintains its place in
+the sequence order. Before an instance of a recurring event is edited, it is
+considered a ghost event, or a placeholder. This means that there is no
+database entry for that instance. Rather, when querying for events, if a
+recurring series of events overlaps with the query range, instance
+placeholders of that recurring event are generated and are displayed for
+that range. If a placeholder instance of a recurring event is edited, a real
+entry in the database is created and all changes are saved. When that
+instance falls within a query range, the real instance event replaces the
+old placeholder instance.
+
+To prevent disordering of the recurring sequence of events, parent recurring
+events do not allow editing of date-related fields like recurrence frequency
+and recurrence start and end dates. If all instances of the recurring event
+need to be rescheduled, users are encouraged to cancel a recurring event and
+create a new recurring event with the revised date and time.
+
+
+Cancelling Events
+=================
+
+Cancelling basic events will hide that event from most of the builtin Calendar
+queries, unless the query specifies to display cancelled events.
+
+There are two ways to cancel an instance of a recurring event.
+
+- Cancel an instance of a recurring event.
+- Cancel the entire series of a recurring event.
+
+Cancelling a placeholder instance of a recurring event will create a real
+cancelled event that will replace the placeholder instance. Consequently,
+the cancellation status of that instance of the recurring event will
+persist if the parent event is cancelled and subsequently reinstated.
+
+When an entire series of a recurring event is cancelled, all the placeholder
+and real instances are also cancelled. An entire series can similarly be
+reinstated, but it is currently not possible to reinstate an instance of a
+cancelled recurring event series. To reinstate that instance, the entire
+series must be reinstated. If an instance of a recurring event has been
+cancelled, then the entire recurring event series is also cancelled,
+reinstating the series will not reinstate the previously cancelled instances
+of that event.
+
+
+Commenting On Recurring Events
+==============================
+
+If a placeholder instance of a recurring event has not been converted to a
+real instance of the series as a result of editing or cancelling, commenting on
+that placeholder instance does not currently save a draft for that instance
+only. The draft is saved for the recurring event parent, so the parent
+recurring event and all placeholder instances will show that draft. When a
+comment is actually added to a placeholder instance, the instance is converted
+to a recurrence exception, and the comment will only appear on that instance
+of the recurring event.