add use_chart_version config

- prefix version with `-0.dev.git.{n}.h{sha}` or `-existingPreRelease.git.{n}.h{sha}`
- optionally get base version from Chart.version
- reset only strips git suffix instead of clobbering with resetVersion

Author: minrk

README.md

@@ -39,11 +39,16 @@ information.
 1. If `tag` (like `0.10.0` or `0.10.0-beta.1`) contains `-`,
    indicating that it is a prerelease,
    the chartpress suffix will be added to the prerelease fields,
-   e.g. `0.10.0-beta.1.0git.5.habc123`
-   format will be used instead of a `tag-0git.n.h` format to be SemVer 2 compliant.
+   e.g. `0.10.0-beta.1.git.5.habc123`
+   format will be used instead of a `tag-0.dev.git.n.h` format to be SemVer 2 compliant.
 1. If `--long` is specified or not. If `--long` is specified, tagged commits
    will always be written out with the `n.h` part appended to it, looking something
-   like `1.0.0-0git.0.habcd123`
+   like `1.0.0-0.dev.git.0.habcd123`
+
+When producing a development version (with `.git.n.hash` on the end),
+The _base_ version can come from one of two places,
+depending on your configuration.
+See [Controlling development version](#controlling-development-versions-in-chart.yaml) for more info.
 
 ### Examples chart versions and image tags
 
@@ -52,13 +57,13 @@ order that could come from using chartpress.
 
 ```
 0.8.0
-0.8.0-0git.4.hasdf123
-0.8.0-0git.10.hsdfg234
+0.8.0-0.dev.git.4.hasdf123
+0.8.0-0.dev.git.10.hsdfg234
 0.9.0-beta.1
-0.9.0-beta.1.0git.1.hdfgh345
-0.9.0-beta.1.0git.5.hfghj456
+0.9.0-beta.1.git.1.hdfgh345
+0.9.0-beta.1.git.5.hfghj456
 0.9.0-beta.2
-0.9.0-beta.2.0git.1.hghjk567
+0.9.0-beta.2.git.1.hghjk567
 0.9.0-beta.3
 0.9.0
 ```
@@ -170,6 +175,12 @@ charts:
     # --reset flag. It defaults to "0.0.1-set.by.chartpress". This is a valid
     # SemVer 2 version, which is required for a helm lint command to succeed.
     resetVersion: 1.2.3
+    # Use the version in Chart.yaml for the base version,
+    # instead of the latest tag from `git describe`
+    # This gives you more control over development version tags
+    # and lets you ensure prerelease tags are always sorted in the right order
+    useChartVersion: true
+
     # The git repo whose gh-pages contains the charts. This can be a local
     # path such as "." as well but if matching <organization>/<repo> will be
     # assumed to be a separate GitHub repository.
@@ -223,6 +234,83 @@ charts:
           - linux/arm64
 ```
 
+### Controlling development versions in Chart.yaml
+
+Like some "package version in version control" tools,
+you don't need to manage versions at all in chartpress except by tagging commits.
+
+However, relying only on tags results in "development versions" (versions published from commits after a release)
+having somewhat confusing prerelease versions.
+
+After publishing e.g. `1.2.3`, the next version will be `1.2.3-0.dev.git.1.habc`.
+According to Semantic Versioning,
+this is a "pre release" (good, it should be excluded from default installation),
+but it means it comes _before_ 1.2.3 (wrong! it's 1 commit _newer_ than 1.2.3).
+This is because prereleases should be defined relative to the _next_ release,
+not the _last_ release. But git tags only store the _last_ release!
+
+Chartpress 2.0 adds an option `chart.useChartVersion`,
+which changes the base version to use when setting the chart version.
+Instead of using the version of the last tag found via `git describe`,
+it uses the version found in Chart.yaml.
+
+The main benefits of this are:
+
+1. ensuring that published prerelease versions show up in the right order, and
+2. giving you control over the version of a prerelease chart (is it 2.0.0-0.dev or 1.3.1-0.dev?)
+
+Instead of publishing the sequence:
+
+- 1.2.3
+- 1.2.3-0.dev.git.1.habc (later than 1.2.3, but sorts _before_ 1.2.3!)
+
+You can publish
+
+- 1.2.3
+- 1.3.0-0.dev.git.1.habc (prerelease based on the _next_ version, not _last_)
+
+where chartpress will use the version in your Chart.yaml as the base version,
+instead of the last tag on the branch.
+
+This takes some extra configuration, and steps in your release process
+to update the version in your Chart.yaml.
+
+1. You must set `useChartVersion: true` in your chartpress.yaml:
+
+   ```yaml
+   charts:
+     - name: mychart
+       useChartVersion: true
+   ```
+
+2. You must control the version in Chart.yaml, especially after making a release.
+
+A release process would generally look like this:
+
+```bash
+V=1.2.3
+chartpress --reset --tag "$V"
+git commit -am "release $V"
+git tag -am "release $V" "$V"
+git push --atomic --follow-tags
+
+# back to development
+NEXT_V=1.3.0-0.dev
+chartpress --reset --tag "$NEXT_V"
+git commit -am "Back to $NEXT_V"
+git push --atomic
+```
+
+Any prerelease fields (such as `-0.dev` above, or `-alpha.1`)
+will be left as-is, with the `.git.n.hash` suffix added.
+
+If the version in Chart.yaml is not a prerelease,
+a prelease version will be constructed with `-0.dev.git.n.hash`.
+
+When you use this configuration,
+`chartpress --reset` strips the `.git...` suffix from the chart version,
+ignoring the `resetVersion` config.
+
 ## Caveats
 
 ### Shallow clones

chartpress.py

@@ -29,8 +29,15 @@
 # name of possible repository keys used in image value
 IMAGE_REPOSITORY_KEYS = {"name", "repository"}
 
-# prefix in prerelease tag for git commit count
-PRERELEASE_PREFIX = "0git."
+# prefixes added to prerelease versions
+# these do not include the trailing '.'
+# which makes them valid prerelease fields on their own,
+# but they cannot be empty.
+
+# GIT is always added to start our git info
+GIT_PREFIX = "git"
+# this is the _full_ prefix we add to non-prerelease versions
+PRERELEASE_PREFIX = f"0.dev.{GIT_PREFIX}"
 
 # Container builders
 class Builder(Enum):
@@ -442,7 +449,7 @@ def _image_needs_building(image, platforms):
     return _image_needs_pushing(image, platforms)
 
 
-def _get_identifier_from_paths(*paths, long=False):
+def _get_identifier_from_paths(*paths, long=False, base_version=None):
     latest_commit = _get_latest_commit_tagged_or_modifying_paths(*paths, echo=False)
 
     try:
@@ -456,24 +463,29 @@ def _get_identifier_from_paths(*paths, long=False):
             .strip()
         )
         latest_tag_in_branch, n_commits, sha = git_describe.rsplit("-", maxsplit=2)
+        n_commits = int(n_commits)
+        if base_version is None:
+            base_version = latest_tag_in_branch
         # remove "g" prefix output by the git describe command
         # ref: https://git-scm.com/docs/git-describe#_examples
         sha = sha[1:]
-
-        return _get_identifier_from_parts(latest_tag_in_branch, n_commits, sha, long)
     except subprocess.CalledProcessError:
         # no tags on branch, so assume 0.0.1 and
         # calculate n_commits from latest_commit
-        n_commits = (
+        n_commits = int(
             _check_output(
                 ["git", "rev-list", "--count", latest_commit],
                 echo=False,
             )
             .decode("utf-8")
             .strip()
         )
+        sha = latest_commit
+
+    if base_version is None:
+        base_version = "0.0.1"
 
-        return _get_identifier_from_parts("0.0.1", n_commits, latest_commit, long)
+    return _get_identifier_from_parts(base_version, n_commits, sha, long)
 
 
 def _get_identifier_from_parts(tag, n_commits, commit, long):
@@ -487,25 +499,34 @@ def _get_identifier_from_parts(tag, n_commits, commit, long):
     with h to ensure we don't get a numerical hash starting with 0 because
     those are invalid SemVer 2 versions.
 
-    We lead with '0git.' to ensure our suffixes sort as older than any explicit tags,
-    such as `0.1.2-alpha.1 > 0.1.2-alpha.0git.5.habc > 0.1.2-0git.3.h123`
+    If tag is already a prelease, we append fields so we sort later than the prerelease.
+    If the tag is a stable release, we start the prerelease with `-0.dev.` to ensure we sort lower
+    than labeled prereleases such as 'alpha'.
+
+    Typical tags in descending order:
+
+    - 0.1.2
+    - 0.1.2-alpha.2
+    - 0.1.2-alpha.1.git.5.habc
+    - 0.1.2-alpha.1
+    - 0.1.2-0.dev.git.3.habc
 
     Example:
         tag="0.1.2", n_commits="5", commit="asdf1234", long=True,
-        should return "0.1.2-0git.5.hasdf1234".
+        should return "0.1.2-0.dev.git.5.hasdf1234".
     """
     n_commits = int(n_commits)
 
     if n_commits > 0 or long:
         if "-" in tag:
-            # add a field to an existing prerelease tag
-            # 0.1.2-alpha.1 -> 0.1.2-{PRERELEASE_PREFIX}5.hsha
-            sep = "."
+            # add fields to an existing prerelease tag
+            # 0.1.2-alpha.1 -> 0.1.2-alpha.1.git.n.hsha
+            pre = f".{GIT_PREFIX}"
         else:
-            # create prerelease tag
-            # 0.1.2-alpha.1 -> 0.1.2-{PRERELEASE_PREFIX}5.hsha
-            sep = "-"
-        return f"{tag}{sep}{PRERELEASE_PREFIX}{n_commits}.h{commit}"
+            # create a new '-0.dev.' prerelease tag
+            # 0.1.2 -> 0.1.2-0.dev.git.5.hsha
+            pre = f"-{PRERELEASE_PREFIX}"
+        return f"{tag}{pre}.{n_commits}.h{commit}"
     else:
         return f"{tag}"
 
@@ -522,6 +543,7 @@ def build_images(
     *,
     builder=Builder.DOCKER_BUILD,
     platforms=None,
+    base_version=None,
 ):
     """Build a collection of docker images
 
@@ -549,11 +571,11 @@ def build_images(
 
         Example 1:
         - long=False: 0.9.0
-        - long=True:  0.9.0-0git.0.hasdf1234
+        - long=True:  0.9.0-0.dev.git.0.hasdf1234
 
         Example 2:
-        - long=False: 0.9.0-0git.4.hsdfg2345
-        - long=True:  0.9.0-0git.4.hsdfg2345
+        - long=False: 0.9.0-0.dev.git.4.hsdfg2345
+        - long=True:  0.9.0-0.dev.git.4.hsdfg2345
 
     builder (str):
         The container build engine.
@@ -567,7 +589,9 @@ def build_images(
         all_image_paths = _get_all_image_paths(name, options)
 
         if tag is None:
-            image_tag = _get_identifier_from_paths(*all_image_paths, long=long)
+            image_tag = _get_identifier_from_paths(
+                *all_image_paths, long=long, base_version=base_version
+            )
         else:
             image_tag = tag
 
@@ -709,23 +733,44 @@ def _update_values_file_with_modifications(name, modifications):
         yaml.dump(values, f)
 
 
+_suffix_version_pat = re.compile(r"(.*)\.git\.\d+\.h[a-f0-9]+$")
+
+
+def _trim_version_suffix(version):
+    """Trim trailing .git... suffix from a version
+
+    Turns 1.0.0-0.dev.git.5.habc back into 1.0.0-0.dev
+    """
+    m = _suffix_version_pat.match(version)
+    if m:
+        # matches, strip suffix
+        return m.group(1)
+    return version
+
+
 def build_chart(
-    name, version=None, paths=None, long=False, reset=False, strict_version=False
+    name,
+    version=None,
+    paths=None,
+    long=False,
+    reset=False,
+    strict_version=False,
+    use_chart_version=False,
 ):
     """
     Update Chart.yaml's version, using specified version or by constructing one.
 
     Chart versions are constructed using:
-        a) the latest commit that is tagged,
+        a) a base version, derived from either Chart.yaml or the latest tag
         b) the latest commit that modified provided paths
 
     Example versions constructed:
+        - 0.9.0-0.dev.git.2.hdfgh3456
         - 0.9.0-alpha.1
-        - 0.9.0-alpha.1.0git.0.hasdf1234 (--long)
-        - 0.9.0-alpha.1.0git.5.hsdfg2345
-        - 0.9.0-alpha.1.0git.5.hsdfg2345 (--long)
+        - 0.9.0-alpha.1.git.0.hasdf1234 (--long)
+        - 0.9.0-alpha.1.git.5.hsdfg2345
+        - 0.9.0-alpha.1.git.5.hsdfg2345 (--long)
         - 0.9.0
-        - 0.9.0-0git.2.hdfgh3456
     """
     # read Chart.yaml
     chart_file = os.path.join(name, "Chart.yaml")
@@ -734,7 +779,23 @@ def build_chart(
 
     # decide a version string
     if version is None:
-        version = _get_identifier_from_paths(*paths, long=long)
+        if use_chart_version:
+            # avoid adding .git... to chart version multiple times!
+            base_version = _trim_version_suffix(chart["version"])
+            # TODO: trim -set.by.chartpress?
+            # if base_version.endswith("-set.by.chartpress"):
+            #     base_version = base_version.rsplit("-", 1)[0]
+        else:
+            base_version = None
+        if reset:
+            # resetting, use the base version without '.git...'
+            version = base_version
+        else:
+            # derive the full version, with possible '.git...'
+            version = _get_identifier_from_paths(
+                *paths, long=long, base_version=base_version
+            )
+
     if not reset:
         version = _fix_chart_version(version, strict=strict_version)
 
@@ -1008,10 +1069,16 @@ def main(args=None):
     #   - push chart (--publish-chart, --extra-message)
     for chart in config["charts"]:
         forced_version = None
+        # TODO: maybe warn and switch default in the future?
+        use_chart_version = chart.get("useChartVersion", False)
+
         if args.tag:
+            # tag specified, use that version
             forced_version = args.tag
-        elif args.reset:
-            forced_version = chart.get("resetVersion", "0.0.1-set.by.chartpress")
+        elif args.reset and not use_chart_version:
+            # resetting, get version from chrtpress.yaml,
+            # ignoring current version in Chart.yaml
+            forced_version = chart.get("resetVersion", "0.0.1-0.dev")
 
         if not args.list_images:
             # update Chart.yaml with a version
@@ -1022,6 +1089,7 @@ def main(args=None):
                 long=args.long,
                 reset=args.reset,
                 strict_version=args.publish_chart,
+                use_chart_version=use_chart_version,
             )
 
         if "images" in chart: