search

nedbat / scriv

Changelog management tool
https://scriv.readthedocs.io
Apache License 2.0
260 stars 29 forks source link

Allow skipping date in the version header #48

Closed maxking closed 2 years ago

maxking commented 2 years ago

So, the intent for me here is to make scriv collect as part of regular documentation build such that the "latest" version of the documentation shows the the unreleased changes made so far.

For example, Scriv's documentation currently has only a placeholder which says

See the fragment files in the [changelog.d directory](https://github.com/nedbat/scriv/tree/master/changelog.d).

IMO it would be slightly better if instead of that we could add scriv collect to the commands in docs testenv for docs.

Doing that with scriv reuses the currently released version number (0.13.0) since it looks like the version number hasn't been updated to 0.14.0-dev or something to signify a dev build. But either way, I can override the version with scriv collect --verison next.

Since it is unreleased, i'd like it to skip the date header though, since it doesn't make sense in the context.

Do you think it is a good enough use case to support another flag, something like --skip-date, to skip addition of date?

maxking commented 2 years ago

Hey @nedbat, any thoughts about this issue?

nedbat commented 2 years ago

For your use, maybe the best thing would be --header=Next or whatever to just set the entire text of the header.

nedbat commented 2 years ago

But also, if you run the command again, it should add content to that header, rather than making a second Next heading, right?

maxking commented 2 years ago

Actually, I didn't notice the --header will override it. I think that should solve my use case.

But also, if you run the command again, it should add content to that header, rather than making a second Next heading, right?

So, my idea is to generate the Next section during the docs build. In the source, we will keep only the fragments until a new release happens. So, ideally, there wouldn't be a situation where we have a Next heading and also fragments.

nedbat commented 2 years ago

Actually, I didn't notice the --header will override it. I think that should solve my use case.

Sorry, I wasn't clear: there is no --header option yet.

So, my idea is to generate the Next section during the docs build. In the source, we will keep only the fragments until a new release happens. So, ideally, there wouldn't be a situation where we have a Next heading and also fragments.

I don't understand the flow here. When does the docs build happen? I thought you wanted a way to gradually collect entries in an "Unreleased" or "Next" section, the way people do manually? Can you explain what you mean by a "docs build"?

maxking commented 2 years ago

I don't understand the flow here. When does the docs build happen? I thought you wanted a way to gradually collect entries in an "Unreleased" or "Next" section, the way people do manually? Can you explain what you mean by a "docs build"?

"docs build" essentially mean when we generate HTML using sphinx form the .rst (or whatever), most importantly on readthedocs for me.

The idea is that I will keep all the entries in changelog.d until a release, but before we do sphinx-build (which happens on each commit), we will run scriv collect --header="Next" such that all the un-release entries also show up in the NEWS.rst file. The changes made by scriv collect --header="Next" are never checked in VCS. Only when we are ready for a reelease, we will do a scriv collect with the right version number and commit then changes to VCS, cleaning out the changelogs.d.

Hopefully, that explains the flow better.

nedbat commented 2 years ago

Thanks for the explanation, and sorry for the delay.

This is now implemented in c87162a, as collect --title=TEXT.

nedbat commented 2 years ago

This is now released as part of scriv 0.17.0.