Deprecate support for 'partial' versions.rba/pre-2.8

Their comparison semantics were ill-defined, and mostly an
implementation detail for the old, 'native' specs.

6 files changed, 21 insertions, 8 deletions

diff --git a/ChangeLog b/ChangeLog
index 9fbcae6..452961f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -22,6 +22,7 @@ ChangeLog
 
     * Deprecate the ``Spec`` class (Removed in 3.1); use the ``SimpleSpec`` class instead
     * Deprecate the internal ``SpecItem`` class (Removed in 3.0).
+    * Deprecate the ``partial=True`` form of ``Version``; use ``SimpleSpec`` instead.
 
 *Removed:*
 
diff --git a/README.rst b/README.rst
index 2adef1b..ef824ea 100644
--- a/README.rst
+++ b/README.rst
@@ -103,14 +103,6 @@ If the provided version string is invalid, a :exc:`ValueError` will be raised:
         raise ValueError('Invalid version string: %r' % version_string)
     ValueError: Invalid version string: '0.1'
 
-In order to define "relaxed" version strings, you must pass in ``partial=True``:
-
-.. code-block:: pycon
-
-    >>> v = semantic_version.Version('0.1', partial=True)
-    >>> list(v)
-    [0, 1, None, None, None]
-
 
 Obviously, :class:`Versions <Version>` can be compared:
 
diff --git a/docs/django.rst b/docs/django.rst
index 382b332..34a0fe3 100644
--- a/docs/django.rst
+++ b/docs/django.rst
@@ -18,6 +18,9 @@ with their :attr:`~django.db.models.CharField.max_length` defaulting to 200.
 
     .. attribute:: partial
 
+        .. deprecated:: 2.7
+            Support for partial versions will be removed in 3.0.
+
         Boolean; whether :attr:`~semantic_version.Version.partial` versions are allowed.
 
     .. attribute:: coerce
diff --git a/docs/reference.rst b/docs/reference.rst
index 3495940..1c4f0cf 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -95,6 +95,10 @@ Representing a version (the Version class)
         ``bool``, whether this is a 'partial' or a complete version number.
         Partial version number may lack :attr:`minor` or :attr:`patch` version numbers.
 
+        .. deprecated:: 2.7
+            The ability to define a partial version will be removed in version 3.0.
+            Use :class:`SimpleSpec` instead: ``SimpleSpec('1.x.x')``.
+
     .. attribute:: major
 
         ``int``, the major version number
diff --git a/semantic_version/base.py b/semantic_version/base.py
index 0e036ae..fb8205c 100644
--- a/semantic_version/base.py
+++ b/semantic_version/base.py
@@ -91,6 +91,12 @@ class Version:
             prerelease=None,
             build=None,
             partial=False):
+        if partial:
+            warnings.warn(
+                "Partial versions will be removed in 3.0; use SimpleSpec('1.x.x') instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         has_text = version_string is not None
         has_parts = not (major is minor is patch is prerelease is build is None)
         if not has_text ^ has_parts:
diff --git a/semantic_version/django_fields.py b/semantic_version/django_fields.py
index 1af5bf5..db7e606 100644
--- a/semantic_version/django_fields.py
+++ b/semantic_version/django_fields.py
@@ -2,6 +2,7 @@
 # Copyright (c) The python-semanticversion project
 # This code is distributed under the two-clause BSD License.
 
+import warnings
 
 from django.db import models
 from django.utils.translation import ugettext_lazy as _
@@ -46,6 +47,12 @@ class VersionField(SemVerField):
 
     def __init__(self, *args, **kwargs):
         self.partial = kwargs.pop('partial', False)
+        if self.partial:
+            warnings.warn(
+                "Use of `partial=True` will be removed in 3.0.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         self.coerce = kwargs.pop('coerce', False)
         super().__init__(*args, **kwargs)