search

twisted / towncrier

Manage the release notes for your project.
https://towncrier.readthedocs.io
MIT License
790 stars 122 forks source link

Add support for $NEXT_RELEASE$ source code placeholder / keyword substitution #579

Open adiroiban opened 7 months ago

adiroiban commented 7 months ago

This is designed as the next step after removing incremental.

Incremental has a nice feature that allowes to replace the NEXT placeholder in the source code, with the value of the current release number.

This is similar to keywords substitution from CVS but the use case is a different.

The use case is something like this:

During development you add various features in various branches. When you first implement a change or when you send to review, you don't know the exact version number in which that feature is released.

Any text reference to the version number is replaced at development time with the $NEXT_VERSION$

The branch and merged with source code including the $NEXT_VERSION$ text.

At release time, you run towncrier and towncrier will replace the source code with the actual release number.

I think that it makes sense to have this functionality in towncrier

When you run towncrier, it will delele the release notes fragments ... so it is already modifying the source code.

Also, when you run towncrier it knows the current release version.

The placeholder can also be $NEXT_RELEASE$ or $NEXT_TOWNCRIER_RELEASE$ or something else. The important part is to make sure it will not overlap with other texts in the source code.

This should be a very simple text replacement. In this way, you can use the value in Python, RST, JavaScript or any other text file.

adiroiban commented 2 months ago

One important feature is to make sure that towncrier check , when executed for a release branch will make sure the source code has no $NEXT_RELEASE$ marker

The problem with $NEXT_RELEASE$ replacement is implemeting a process in which you first do a release candidate, and then you update to the development process.

Possible transitions

  1. Dev -> Final release
  2. Dev -> Release Candidate 1
  3. Release Candidate 1 -> Release Candidate 2
  4. Release candidate -> Final release
  5. Final release -> Dev

Other than case 5 (Final release -> Dev) for each transition the release version should be updated.

For case 1, things are simple, as you just do a replacement. For the other cases are more complicated as the version is already resolved.

Maybe when the version placeholder is replace, we can keep some commented code to allow a future replacement.