Merge branch 'al-211337-version-control-for-snippets-documentation' into 'master'

Add documentation about Versioned Snippets

See merge request gitlab-org/gitlab!30559

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).
 
@@ -11,6 +11,67 @@ There are two types of snippets:
 - Personal snippets.
 - Project snippets.
 
+## 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 50MB, by default.
+
 ## Personal snippets
 
 Personal snippets are not related to any project and can be created completely