Add latest changes from gitlab-org/gitlab@13-0-stable-ee

1 files changed, 64 insertions, 3 deletions

diff --git a/doc/user/snippets.md b/doc/user/snippets.md
index 0372bb42038..96c8dba11e5 100644
--- a/doc/user/snippets.md
+++ b/doc/user/snippets.md
@@ -2,7 +2,7 @@
 
 With GitLab Snippets you can store and share bits of code and text with other users.
 
-![GitLab Snippet](img/gitlab_snippet.png)
+![GitLab Snippet](img/gitlab_snippet_v13_0.png)
 
 Snippets can be maintained using [snippets API](../api/snippets.md).
 
@@ -49,6 +49,67 @@ CAUTION: **Warning:**
 Make sure to add the file name to get code highlighting and to avoid this
 [copy-pasting bug](https://gitlab.com/gitlab-org/gitlab/-/issues/22870).
 
+## Versioned Snippets
+
+> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/239) in GitLab 13.0.
+
+Starting in 13.0, snippets (both personal and project snippets)
+have version control enabled by default.
+
+This means that all snippets get their own underlying repository initialized with
+a `master` branch at the moment the snippet is created. Whenever a change to the snippet is saved, a
+new commit to the master branch is recorded. Commit messages are automatically
+generated. The snippet's repository has only one branch (master) by default, deleting
+it or creating other branches is not supported.
+
+Existing snippets will be automatically migrated in 13.0. Their current
+content will be saved as the initial commit to the snippets' repository.
+
+### File names
+
+Snippets support syntax highlighting based on the filename and
+extension provided for them. While it is possible to submit a snippet
+without specifying a filename and extension, it needs a valid name so the
+content can be created as a file in the snippet's repository.
+
+In case the user does not attribute a filename and extension to a snippet,
+GitLab automatically adds a filename in the format `snippetfile<x>.txt`
+where `<x>` represents a number added to the file, starting with 1. This
+number increases incrementally when more snippets without an attributed
+filename are added.
+
+When upgrading from an earlier version of GitLab to 13.0, existing snippets
+without a supported filename will be renamed to a compatible format. For
+example, if the snippet's filename is `http://a-weird-filename.me` it will
+be changed to `http-a-weird-filename-me` to be included in the snippet's
+repository. As snippets are stored by ID, changing their filenames will not break
+direct or embedded links to the snippet.
+
+### Cloning snippets
+
+Snippets can be cloned as a regular Git repository using SSH or HTTPS. Click the **Clone**
+button above the snippet content to copy the URL of your choice.
+
+![Clone Snippet](img/snippet_clone_button_v13_0.png)
+
+This allows you to have a local copy of the snippet's repository and make
+changes as needed. You can commit those changes and push them to the remote
+master branch.
+
+### Limitations
+
+- Binary files are not supported.
+- Creating or deleting branches is not supported. Only a default *master*.
+branch is used.
+- Git tags are not supported in snippet repositories.
+- Snippets' repositories are limited to one file. Attempting to push more
+than one file will result in an error.
+- Revisions are not *yet* visible to the user on the GitLab UI, but
+it's planned to be added in future iterations. See the [revisions tab issue](https://gitlab.com/gitlab-org/gitlab/-/issues/39271)
+for updates.
+- The [maximum size for a snippet](../administration/snippets/index.md#snippets-content-size-limit)
+is 50 MB, by default.
+
 ## Discover snippets
 
 There are two main ways of how you can discover snippets in GitLab.
@@ -87,7 +148,7 @@ snippet was created using the GitLab web interface the original line ending is W
 > Introduced in GitLab 10.8.
 
 Public snippets can not only be shared, but also embedded on any website. This
-allows to reuse a GitLab snippet in multiple places and any change to the source
+allows us to reuse a GitLab snippet in multiple places and any change to the source
 is automatically reflected in the embedded snippet.
 
 To embed a snippet, first make sure that:
@@ -111,6 +172,6 @@ Here's how an embedded snippet looks like:
 
 <script src="https://gitlab.com/gitlab-org/gitlab-foss/snippets/1717978.js"></script>
 
-Embedded snippets are displayed with a header that shows the file name if defined,
+Embedded snippets are displayed with a header that shows the file name is defined,
 the snippet size, a link to GitLab, and the actual snippet content. Actions in
 the header allow users to see the snippet in raw format and download it.