Support replacing a placeholder string only once during the next version bump

[edgarrmondragon]

Description

I'm using Sphinx to document my Python project, which has a versionadded and versionchanged directives for rendering the version a feature was added.

For example:

def a_new_function():
  """A simple function.

  .. versionadded:: 0.1.0
  .. versionchanged:: 0.1.1  (could also be 0.2.0 if some features landed before the release)
  Return float.
  """
  return 1.0

The problem is, I don't always know what the next version will be, which most of the time is either a patch or a minor bump, so I'd like to configure commitizen with custom strings that it can change and replace with the new version in the project tree, so I can do something like:

def a_new_function():
  """A simple function.

  .. versionadded:: 0.1.0
  .. versionchanged:: NEXT_VERSION
  Return float.
  """
  return 1.0

without having to think what the next version will be.

Possible Solution

Perhaps something like this:

[tool.commitizen]
replace_with_version = "NEXT_VERSION"

Additional context

In the past I've used a similar tool called Changie that supports a replacements option:

# .changie.yaml
- path: src/mylib/client.py
  find: "NEXT_VERSION"
  replace: "{{.VersionNoPrefix}}"

Additional context

No response

[woile]

Do you want versionchanged:: 0.1.1 to be updated on every new release?

[edgarrmondragon]

Do you want versionchanged:: 0.1.1 to be updated on every new release?

Not really. Only following the first cz bump after a new versionchanged:: NEXT_VERSION is added to the codebase.

In fact, there could be multiple versionchanged for each function, class, etc. For example:

def a_new_function():
  """A simple function.

  .. versionadded:: 0.1.0

  .. versionchanged:: 0.1.1
  Return float.

  .. versionchanged:: 0.2.0
  Return 2.0 if FEATURE_FLAG is set.
  """
  if FEATURE_FLAG:
    return 2.0
  return 1.0

EDIT: I've update the issue title to better reflect the feature I'm describing 🙂

[woile]

I like the idea, what do you think @noirbizarre @Lee-W ?

What I don't like from the example is that once you update with the new version, this block:

# .changie.yaml
- path: src/mylib/client.py
  find: "NEXT_VERSION"
  replace: "{{.VersionNoPrefix}}"

is meaningless, but it's more efficient than looking up all the files

[Lee-W]

I'm good with this feature 👍