Add version requirements to docs

docs/docsite/rst/contributing/creating_role.rst

@@ -117,31 +117,43 @@ the default metadata file created by the ``init`` command:
 The following provides guidance on setting some of the metadata values that may not be so obvious:
 
 role_name
-    Use this to override the name of the role. In the past, Galaxy would apply a regex expression to the GitHub repository name and
+    Optional. Use to override the name of the role.
+
+    In the past, Galaxy would apply a regex expression to the GitHub repository name and
     automatically remove 'ansible-' and 'ansible-role-'. For example, if your repository name was 'ansible-role-apache', the role name
     would translate to 'apache'. Galaxy no longer does this automatically. Instead, use the *role_name* setting to tell Galaxy what
     the role name should be.
 
     If no value is provided, then the role name will match the repository name, with a couple of exceptions, including:
     converting the name to all lowercase, and replacing any '-' or '.' characters with '_'.
 
+    .. note::
+
+        The value of *role_name* will be converted to lowercase, and '-' and '.' will be translated to '_'.
+
+    .. note::
+
+        Setting the value of *role_name* on an existing role will change the name of the role by
+        converting it to lowercase, and translating '-'  and '.' to '_'. If the name
+        of an existing role should not be altered, don't set the value of *role_name*.
+
 platforms
-    Provide a list of valid platforms, and for each platform, a list of valid versions. The obvious question of course is, where does one
+    Required. Provide a list of valid platforms, and for each platform, a list of valid versions. The obvious question of course is, where does one
     find the list of valid platforms? You can find the `list of platforms here </api/v1/platforms/>`_. The list
     is paginated. Click on the ``next_link`` value to get to view the next page. It's not the pretiest interface, but for now, it works.
 
     You can also search by name. For example, to search for all Ubuntu versions by adding ``?name__icontains=ubuntu`` to the query. The full
     URL will be `https://galaxy.ansible.com/api/v1/platforms/?name__icontains=ubuntu <https://galaxy.ansible.com/api/v1/platforms/?name__icontains=ubuntu>`.
 
 galaxy_tags
-    Provide a list of tags. A tag is a single world that helps categorize your role. You can invent tags, or guess at tags other might be
+    Optional. Provide a list of tags. A tag is a single world that helps categorize your role. You can invent tags, or guess at tags other might be
     using to describe similar roles, but why do that, when you can see what others are using by `browsing existing tags here <https://galaxy-qa.ansible.com/api/v1/tags/>`_.
 
     As with *platforms*, you can search by name here as well. For example, to see if the 'database' tag exists, add ``?name_icontains=database``
     to the query. The full URL will be `https://galaxy.ansible.com/api/v1/tags/?name__icontains=database <https://galaxy.ansible.com/api/v1/tags/?name__icontains=database>`_.
 
 dependencies
-    In a nutshell, dependencies are installed when the role is installed, and dependencies are executed before the role is executed. During role
+    Optional. In a nutshell, dependencies are installed when the role is installed, and dependencies are executed before the role is executed. During role
     install and execution, dependencies are recursive, meaning dependencies can have dependencies. If a role appears more than once in the
     dependency chaing, it will only be executed one time, provided that parameters defined on the dependency are not different. 
 
@@ -173,4 +185,8 @@ To override the default name, set the ``role_name`` attribute in the role ``meta
     Role names are limited to lowercase word characters (i.e., a-z, 0-9) and '_'. No special characters are allowed, including '.',
     '-', and space. During import, any '.' and '-' characters contained in the repository name or role_name will be replaced with '_'.
 
-.. _creating_multirole_repos:
+.. note::
+
+    Setting the value of *role_name* on an existing role will change the name of the role by converting it
+    to lowercase, and translating '-'  and '.' to '_'. If the name of an existing role should not be
+    altered, don't set the value of *role_name*.

docs/docsite/rst/contributing/importing.rst

@@ -176,18 +176,12 @@ changes, as shown below:
 Namespace Limitations
 =====================
 
-Namespace names in Galaxy are limited to lowercase word characters (i.e., A-Z, a-z, 0-9) and '_', must have a minimum length of 2
+Namespace names in Galaxy are limited to lowercase word characters (i.e., a-z, 0-9) and '_', must have a minimum length of 2
 characters, and cannot start with an '_'.
 
 No other characters are allowed, including '.', '-', and space. The first time you log into Galaxy, the server will create a Namespace
 for you, if one does not already exist, by converting your username to lowercase, and replacing any '-' characters with '_'.
 
-.. Note::
-
-   During the upgrade of the Galaxy server from v2.4 to v3.0 Galaxy Namespaces were created for any GitHub usernames and organization
-   names associated with role repositories, and '-' characters were converted to '_'. You may have previously accessed a role from Galaxy
-   where the namespace contained a '-'; however, to access that same role now, you'll need to replace '-' with '_'.
-
 Content Name Limitations
 ========================
 
@@ -238,6 +232,19 @@ rather than the repository name.
     Content names are limited to lowercase word characters (i.e., a-z, 0-9) and '_'. No special characters are allowed, including '.',
     '-', and space. During import, any '.' and '-' characters contained in the repository name or role_name will be replaced with '_'.
 
+.. note::
+
+    Setting the value of *role_name* on an existing role will change the name of the role by converting it
+    to lowercase, and translating '-'  and '.' to '_'. If the name of an existing role should not be
+    altered, don't set the value of *role_name*.
+
+Content Versions
+================
+
+Galaxy supports versioning content through git tags that match the `Semantic Version format <https://semver.org>`_.
+
+For more on creating tags, view :ref:`versioning_content`.
+
 Travis CI
 =========
 

docs/docsite/rst/contributing/index.rst

@@ -10,4 +10,5 @@ Contributing Content
    creating_role
    creating_multi
    creating_apb
+   version
    importing

docs/docsite/rst/contributing/version.rst

@@ -0,0 +1,27 @@
+.. _versioning_content:
+
+******************
+Versioning Content
+******************
+
+.. contents:: Topics
+
+This topic describes how to version Ansible content
+
+.. _create_content_versions:
+
+Creating Content Versions
+=========================
+
+Galaxy imports content from repositories on GitHub, and as part of the import process, it scans the
+repository's git tags, looking for any that match the `Semantic Version <https://semver.org>`_ format.
+Tags that match the format are considered to be versions and imported, and those that don't are skipped.
+
+Once content has been pushed to a GitHub repository, it can be versioned by creating a tag using the
+``git tag`` command. For more on how to create tags, view `Git Basics - Tagging <https://git-scm.com/book/en/v2/Git-Basics-Tagging>`_.
+
+.. note::
+
+    Enforcing the Semantic Version format for git tags will enable future releases of Galaxy to lock
+    content versions, guaranteeing the consistency of downloaded content, and paving the way for the
+    `Mazer client <https://github.com/ansible/mazer>`_ to update installed content.