Compare to scriv

[smolijar]

I am investigating file based changelog tools at the moment and two projects that are closes to what I am looking for is Changie and scriv. I can see that Changie is somewhat new. Did you know about the project before starting this one?

How do you think they compare and do you see any advantages disadvantages between them? What is the reason you would chose Changie over scriv and in what way was scriv not sufficient?

[miniscruff]

I have not heard of scriv, I did compare changie to town crier another python changelog tool. The main differences that I can see compared to scriv are:

1. Changie uses a prompt-based metadata file as opposed to a simple text file. This allows you to create a fragment file from a customized list of prompt choices, with basic validation. This is the main difference I see in Changie compared to other tools. See https://github.com/miniscruff/changie/blob/main/.changie.yaml for the custom issue prompt and change format with the GitHub issue link. Scriv seems to just use a basic text file, as do most other changelog management tools. This is the main reason I created Changie as I find step-by-step tools with validations much nicer overall than magic string commit message checks or blanket text files where anything goes.
2. To see the end result of the prompt base method see how Changie updates each has a consistent format https://github.com/miniscruff/changie/blob/main/CHANGELOG.md where scriv updates are slightly different https://github.com/nedbat/scriv/blob/master/CHANGELOG.rst. Things like where the issue number is referenced or how it is formatted. This was a minor case of OCD for me but with a large set of changes over a long period of time, it can make it easier or harder to read.
3. Changie uses two commands to go from fragments to the main CHANGELOG file. changie batch VERSION && changie merge, compared to scriv and I believe all others having only one scriv collect. Changie does this to allow you to add custom headers and to use the intermediate files as release notes for GitHub releases or other public releases where you only want one version at a time. See the files here https://github.com/miniscruff/changie/tree/main/changes which is used to add notes to releases here https://github.com/miniscruff/changie/releases.
4. Changie is using go so you can install it with a single binary and does not require having go installed, so I would say its language agnostic whereas scriv being written in python will require python ( I originally wrote changie in python at my last job and rewrote it in go for this reason ).

Nothing else seems to be a big difference, a few preference things like how the latest version is passed into changie but is a config in scriv. Maybe some flags that are unique per project but could be added relatively easily if an issue was created and it fit ( looking at the --add flag to add files to git ). This is, of course, a high-level comparison but I think should be enough to point out the main differences.

Personally, I would use Changie of course but if you are developing in python and want a python based solution that is only expected to be used in python and scriv works for you then go for it. The final output of the changelog seems to be about the same in either case. I think changie has more customization options if you need them and a language-agnostic tool is my preference nowadays. ( It is possible to distribute python this way but is much harder and does not seem like scriv is doing so )

Let me know if that helps or if you or if you have further questions. I have also offered to assist in automating releases using Changie in a blog post.

[smolijar]

I wanted to work with multiline changes, which does not really seem to be working well within the body.

I think what scriv does is that you can define a template for the new change, which is a simple markdown. For example I would like the change to have the following format:

## Intro
Description of the merge request in few sentences, that can include some formatting as lists and such
 - foo
 - bar

## Testing
Some comment on how the feature was tested, perhaps some md checkboxes
 - [ ] Added unit tests
 - [ ] Added integration tests

## Tracker
Related to: #123

I understand that the tracker for example is a prime candidate for custom fields. Not sure about the free text.

1. Is there a reasonable way to work with multiline body of change? (because it does not seem to be possible through CLI and editing that in YAML feels like pain)
2. Is there a way to call changie new that would only create the file with some placeholders, ideally from template? The interactive mode is OK, but many people (me including) would maybe prefer just to use their editor.

[smolijar]

Ok, multiline edits in YAML are ok, mb. Maybe there is a way to use a template or custom values with predefined value?

[miniscruff]

I wanted to work with multiline changes, which does not really seem to be working well within the body.

Yes, there is an issue right now that has multiline bodies suggested but I have not started work on it yet. This is mostly due to trying to figure out if there is a more abstract method of handling the different tiers of changelog fragments. Currently, you have the Kinds and under each kind is a list of change fragments. But what if you wanted another level, say component > kind > fragment. That is not really supported by changie or any other changelog tool I know of.

I understand that the tracker for example is a prime candidate for custom fields

The tracker would be a custom option yes.

1. Is there a reasonable way to work with multiline body of change? (because it does not seem to be possible through CLI and editing that in YAML feels like pain)

Currently no. However, I would consider your example a bit much for a single changelog fragment. Consider reading GitLab's blog here https://docs.gitlab.com/ee/development/changelog.html as a good guide for what a changelog entry is expected to look like. Your changelog fragment example looked more like a pull request description, in my opinion.

2. Is there a way to call `changie new` that would only create the file with some placeholders, ideally from template? The interactive mode is OK, but many people (me including) would maybe prefer just to use their editor.

Currently no, but I wouldn't be totally against it. You will lose out on any conditional checks on values. But, it would be no different than just inputting any data and pressing submit. I can make a task for this one, maybe get to it this week. This would not be from a template, but instead, the default values for the body ( which would be empty ), kind ( which I guess could be the first one ), custom templates would be included as the default. For strings that would be empty, numbers would be min if included, max if no min, or 0 if neither. Enums could use the first one.

If this sounds like a good idea let me know.

[smolijar]

How about not using default values, but allow passing them from CLI argument? If you have the values, you would skip them in the interactive mode. This would allow users to write e.g. custom script that leverages git branch name conventions to set the type, you could use it for template as well.

The only issue with not using the template is that the serialization might cause some issues with the multilines. Preferable is IMO to use multiline string | syntax, rather than \n sequences in string.

[miniscruff]

Won't be able to use CLI arguments for custom values, as they are configured per project unless I did some weird hacky behavior to allow creating --custom-choice from some key which does not sound like a good idea. New already supports CLI arguments for body and kind ( at least it should... ).
I am not sure how Golang YAML serializer handles multiline strings yet, ideally yes it would use | syntax.

I do not have much experience here with multi-lines as I exclusively expect changelog fragments to be one or at most two sentences on one line. So, before committing to some method of support I kinda need to try it out myself first... but I really have no use case so its taking a bit.