Merge pull request #1942 from Danielle9897/RDoc-3103-nodejs-revisions…

…Overview

RDoc-3103 [Node.js] Document extensions > Revisions > Overview

Documentation/5.4/Raven.Documentation.Pages/studio/database/document-extensions/revisions.markdown

@@ -0,0 +1,174 @@
+# Document Extensions: Revisions
+---
+
+{NOTE: }
+
+* **Document Revisions** are snapshots of documents that can be created manually or automatically when a document is created, modified, or deleted.
+  Revisions can be used for data auditing, instant restoration after document corruption, and other purposes.
+
+* Learn more about document revisions in this [document revisions overview](../../../document-extensions/revisions/overview):  
+  * To define and enable revisions creation, see [revisions configuration](../../../document-extensions/revisions/overview#revisions-configuration).  
+  * A dynamic walkthrough demonstrating revisions management is available [here](../../../document-extensions/revisions/overview#how-it-works).  
+
+* This article provides an overview of the Studio views related to working with revisions, including:  
+  * Viewing revisions
+  * Comparing revisions
+  * Viewing revisions for deleted documents (Revisions Bin)
+
+---
+
+* In this page:
+  * [Revisions Tab](../../../studio/database/document-extensions/revisions#revisions-tab)  
+  * [Revision inspection](../../../studio/database/document-extensions/revisions#revision-inspection)  
+  * [Revisions comparison](../../../studio/database/document-extensions/revisions#revisions-comparison)  
+  * [Revisions Bin](../../../studio/database/document-extensions/revisions#revisions-bin)  
+     * [Restoring revisions](../../../studio/database/document-extensions/revisions#restoring-revisions)  
+
+{NOTE/}
+
+---
+
+{PANEL: Revisions Tab}
+
+* Located within the Document View,  
+  the Revisions Tab displays the full trail of all revisions created for the document.
+* From this tab, you can inspect each revision, manually force the creation of a new revision,  
+  and compare revisions to the live document version and to other revisions.
+
+![Revisions Tab](images/revisions/document-revisions.png "Revisions Tab")
+
+1. [Document View](../../../studio/database/documents/document-view) > **Revisions tab**  
+   Click to display the document's revisions tab.  
+   Revisions are listed in the revisions tab by their creation time signatures.  
+   The current number of revisions is displayed in the tab header.  
+2. **Create revision**  
+   Click to manually create a new revision for this document from the Studio.  
+   A new revision will be created if the document doesn't already have a revision for the latest content.  
+   [Learn here](../../../document-extensions/revisions/overview#force-revision-creation-via-the-client-api) about forcing the creation of a new revision via the Client API.  
+3. **Revision timestamp**  
+   Click to inspect this revision.  
+4. **Compare revision**  
+   Click to compare this revision with the current live version of the document and with other revisions.  
+
+{PANEL/}
+
+{PANEL: Revision inspection}
+
+Click the revision timestamp to inspect the revision's contents:
+
+![Click to Inspect](images/revisions/click-revision.png "Click to Inspect")
+
+---
+
+The revision will be visible in the Document View,  
+but file editing will Not be available since revisions cannot be modified.
+
+![Revision Inspection](images/revisions/revision-inspection.png "Revision Inspection")
+
+1. **Revision**  
+   The REVISION label indicates that you are viewing a revision and not 
+   the parent document.  
+2. **Clone**  
+   Click to create a document that copies the revision's contents.  
+   {INFO: }
+   * Cloning the revision will open the 'new document view' with this revision's contents.  
+   * You can then save the clone under a new name to create a new document.  
+   * Saving the clone with the exact same ID as the revision's parent document will revert the document to this revision.  
+   {INFO/}
+3. **See the current document**  
+   Click to return to the revision's parent document view.  
+4. **Revision contents**  
+   The content of the revision is displayed in read-only mode.
+
+{PANEL/}
+
+
+{PANEL: Revisions comparison}
+
+Click the revision's comparison button to compare it with other revisions:
+
+![Click to Compare](images/revisions/click-to-compare.png "Click to Compare")
+
+---
+
+![Revision Comparison](images/revisions/revision-comparison.png "Revision Comparison")
+
+1. **Exit revisions compare mode**  
+   Click to exit the comparison window and return to the revisions tTab in the Document View.  
+2. **Compare with**  
+   Click to select a revision to compare with.  
+   ![Compare-with Drop List](images/revisions/compare-with-drop-list.png "Compare-with Drop List")
+3. **Left-hand revision**  
+   The left-hand view displays the revision selected in the revisions tab.  
+4. **Right-hand revision**  
+  The right-hand view displays the revision selected using the "Compare with" drop-down list.  
+5. **Summary line**  
+  This line summarizes the differences found between the two revisions.  
+
+{PANEL/}
+
+{PANEL: Revisions Bin}
+
+* This view displays the revisions of deleted documents.
+
+* When a document is deleted:  
+  * A "delete-revision" is created for the document, marking its deletion.
+  * The "delete-revision" and all the document's revisions - whether automatically created due to the defined revisions configuration or manually created - are moved to the Revisions Bin.
+  * This applies regardless of whether a [revisions configuration](../../../document-extensions/revisions/overview#revisions-configuration) is enabled or disabled.
+
+![Revisions Bin](images/revisions/revisions-bin.png "Revisions Bin")
+
+1. **Revisions Bin**  
+   Click to open the Revisions Bin view.  
+   Each item listed in the Revisions Bin view references all the revisions created for a deleted document.  
+2. **Selection boxes**  
+   Check to select items.  
+3. **Delete**  
+   Click to remove selected items.  
+   Deleting revisions from the Revisions Bin will permanently dispose of these revisions,  
+   making them irrecoverable.
+4. **Deleted document ID**  
+   This is the ID of the document that was deleted.  
+   Click it to inspect the revisions created for this document,  
+   known as "orphaned revisions" since their parent document has been deleted.
+   ![Orphaned Revisions](images/revisions/orphaned-revisions.png "Orphaned Revisions")
+     * Revisions stored in the revisions bin can be [inspected](../../../studio/database/document-extensions/revisions#revision-inspection)
+       and cloned just like the revisions of a live document.  
+5. **Change vector**  
+   The change vector of the revision that was created for the document when it was deleted.  
+6. **Deletion date**  
+   The date/time when the document was deleted.  
+
+---
+
+### Restoring revisions
+
+Giving a **new document** the ID of a deleted document whose revisions are kept in the Revisions Bin,  
+will restore the revisions from the bin and add them to the new document.  
+
+Opening the document's revisions tab will display the whole audit trail,
+including the delete-revision created when the old document was deleted and the revision created when the new document was created.  
+
+![Restored Revisions](images/revisions/restored-revisions.png "Restored Revisions")
+
+{PANEL/}
+
+## Related Articles
+
+### Document Extensions
+
+* [Document Revisions Overview](../../../document-extensions/revisions/overview)  
+* [Revert Revisions](../../../document-extensions/revisions/revert-revisions)  
+* [Revisions and Other Features](../../../document-extensions/revisions/revisions-and-other-features)  
+
+### Client API
+
+* [Revisions: API Overview](../../../document-extensions/revisions/client-api/overview)  
+* [Operations: Configuring Revisions](../../../document-extensions/revisions/client-api/operations/configure-revisions)  
+* [Session: Loading Revisions](../../../document-extensions/revisions/client-api/session/loading)  
+* [Session: Including Revisions](../../../document-extensions/revisions/client-api/session/including)  
+* [Session: Counting Revisions](../../../document-extensions/revisions/client-api/session/counting)  
+
+### Studio
+
+* [Settings: Document Revisions](../../../studio/database/settings/document-revisions)  

Documentation/5.4/Samples/csharp/Raven.Documentation.Samples/DocumentExtensions/Revisions/Revisions.cs

@@ -1,14 +1,13 @@
 using System;
 using System.Collections.Generic;
-using System.Linq;
 using System.Threading.Tasks;
 using Raven.Client;
 using Raven.Client.Documents;
-using Raven.Client.Documents.Operations.Indexes;
 using Raven.Client.Documents.Operations.Revisions;
 using Raven.Client.Documents.Session;
 using Raven.Client.Json;
 using Raven.Documentation.Samples.Orders;
+using Xunit;
 
 namespace Raven.Documentation.Samples.Server
 {
@@ -76,14 +75,14 @@ await store.Maintenance.SendAsync(new ConfigureRevisionsOperation(new RevisionsC
                         .GetMetadataFor("users/1", start: 0, pageSize: 25);
 
                     // Get revisions by their change vectors
-                    User revison = session
+                    User revision = session
                         .Advanced
                         .Revisions
                         .Get<User>(revisionsMetadata[0].GetString(Constants.Documents.Metadata.ChangeVector));
 
                     // Get a revision by its creation time
                     // If no revision was created at that precise time, get the first revision to precede it
-                    User revisonAtYearAgo = session
+                    User revisionAtYearAgo = session
                         .Advanced
                         .Revisions
                         .Get<User>("users/1", DateTime.Now.AddYears(-1));
@@ -101,28 +100,40 @@ public async Task ForceRevisionCreationForSample()
                 {
                     #region ForceRevisionCreationByEntity
                     // Force revision creation by entity
+                    // =================================
+
                     var company = new Company { 
-                            Name = "CompanyProfile" 
+                            Name = "CompanyName" 
                         };
+
                     session.Store(company);
                     companyId = company.Id;
                     session.SaveChanges();
 
                     // Forcing the creation of a revision by entity can be performed 
                     // only when the entity is tracked, after the document is stored.
                     session.Advanced.Revisions.ForceRevisionCreationFor<Company>(company);
+
+                    // Call SaveChanges for the revision to be created
+                    session.SaveChanges();
+
+                    var revisionsCount = session.Advanced.Revisions.GetFor<Company>(companyId).Count;
+                    Assert.Equal(1, revisionsCount);
                     #endregion
                 }
 
                 using (var session = store.OpenSession())
                 {
                     #region ForceRevisionCreationByID
                     // Force revision creation by ID
+                    // =============================
+
                     session.Advanced.Revisions.ForceRevisionCreationFor(companyId);
                     session.SaveChanges();
-                    #endregion
 
                     var revisionsCount = session.Advanced.Revisions.GetFor<Company>(companyId).Count;
+                    Assert.Equal(1, revisionsCount);
+                    #endregion
                 }
             }
         }
@@ -137,6 +148,36 @@ public class Company
             public string Phone { get; set; }
             public string Fax { get; set; }
         }
-
+
+        private interface IFoo
+        {
+            #region syntax_1
+            // Available overloads:
+            // ====================
+
+            // Force revision creation by entity.
+            // Can be used with tracked entities only.
+            void ForceRevisionCreationFor<T>(T entity,
+                ForceRevisionStrategy strategy = ForceRevisionStrategy.Before);
+
+            // Force revision creation by document ID.
+            void ForceRevisionCreationFor(string id,
+                ForceRevisionStrategy strategy = ForceRevisionStrategy.Before);
+            #endregion
+
+            #region syntax_2
+            public enum ForceRevisionStrategy
+            {
+                // Do not force a revision
+                None,
+
+                // Create a forced revision from the document currently in store
+                // BEFORE applying any changes made by the user.
+                // The only exception is for a new document,
+                // where a revision will be created AFTER the update.
+                Before
+            }
+            #endregion
+        }
     }
 }

Documentation/5.4/Samples/nodejs/documentExtensions/revisions/forceRevisionCreation.js

@@ -0,0 +1,61 @@
+import { DocumentStore } from "ravendb";
+
+const documentStore = new DocumentStore();
+
+async function forceRevisionCreation() {
+    {
+        //region force_revision_creation_by_entity
+        // Force revision creation by entity
+        // =================================
+
+        const company = new Company();
+        company.name = "CompanyName";
+
+        const session = documentStore.openSession();
+        await session.store(company);
+        await session.saveChanges();
+
+        // Forcing the creation of a revision by entity can be performed 
+        // only when the entity is tracked, after the document is stored.
+        await session.advanced.revisions.forceRevisionCreationFor(company);
+
+        // Must call 'saveChanges' for the revision to be created
+        await session.saveChanges();
+
+        // Get existing revisions:
+        const revisions = await session.advanced.revisions.getFor(company.id);
+        const revisionsCount = revisions.length;
+
+        assert.equal(revisionsCount, 1);
+        //endregion
+    }
+    {
+        //region force_revision_creation_by_id
+        const company = new Company();
+        company.name = "CompanyName";
+
+        const session = documentStore.openSession();
+        await session.store(company);
+        await session.saveChanges();
+
+        // Force revision creation by ID
+        const companyId = company.id;
+        await session.advanced.revisions.forceRevisionCreationFor(companyId);
+        await session.saveChanges();
+
+        const revisions = await session.advanced.revisions.getFor(company.id);
+        const revisionsCount = revisions.length;
+
+        assert.equal(revisionsCount, 1);
+        //endregion
+    }
+}
+
+//region syntax_1
+// Available overloads:
+// ====================
+forceRevisionCreationFor(entity);
+forceRevisionCreationFor(entity, strategy);
+forceRevisionCreationFor(id);
+forceRevisionCreationFor(id, strategy);
+//endregion

Documentation/5.4/Samples/python/DocumentExtensions/Revisions/Revisions.py

@@ -1,26 +1,23 @@
-from examples_base import ExampleBase, Company
+from ravendb.primitives import constants
+
+from examples_base import ExampleBase
 
 class Force(ExampleBase):
     def setUp(self):
         super().setUp()
 
-    def test_force_revision_creation_for(self):
-        with self.embedded_server.get_document_store("ForceRevision") as store:
-            with store.open_session() as session:
-                self.add_companies(session)
-            company_id = "companies/1"
-            # region force_revision_creation_for
-            with store.open_session() as session:
-                company = session.load(company_id, Company)
-                company.name = "HR V2"
+        # region force_revision_creation_for
+        with self.store.open_session() as session:
+            company = session.load(company_id, Company)
+            company.name = "HR V2"
 
-                session.advanced.revisions.force_revision_creation_for(company)
-                session.save_changes()
+            session.advanced.revisions.force_revision_creation_for(company)
+            session.save_changes()
 
-                revisions = session.advanced.revisions.get_for(company.Id, Company)
-                revisions_count = len(revisions)
+            revisions = session.advanced.revisions.get_for(company.Id, Company)
+            revisions_count = len(revisions)
 
-                self.assertEqual(1, revisions_count)
-                # Assert revision contains the value 'Before' the changes...
-                self.assertEqual("HR V2", revisions[1].name)
-            # endregion
+            self.assertEqual(1, revisions_count)
+            # Assert revision contains the value 'Before' the changes...
+            self.assertEqual("HR", revisions[0].name)
+        # endregion