Differentiate between User API vs. Plugin API changes in changelog #10916
Conversation
# Rust tests and lints will be skipped. Delete if not intended. [ci skip-rust] # Building wheels and fs_util will be skipped. Delete if not intended. [ci skip-build-wheels]
Eric-Arellano
requested review from
jsirois,
benjyw,
tdyas,
asherf,
cosmicexplorer and
gshuflin
| @@ -41,8 +41,12 @@ echo "Potentially relevant headers:" | |||
| echo "----------------------------------------------------------------------------------------------------" | |||
| cat <<EOF | |||
|
|
|||
| API Changes | |||
| ~~~~~~~~~~~ | |||
| User API Changes | |||
There was a problem hiding this comment.
Very open to better names for this. I considered "End-user API changes" also.
There was a problem hiding this comment.
IIUC this is accurate, but also alot of words: Goal, Option and BUILD syntax changes.
| @@ -41,8 +41,12 @@ echo "Potentially relevant headers:" | |||
| echo "----------------------------------------------------------------------------------------------------" | |||
| cat <<EOF | |||
|
|
|||
| API Changes | |||
| ~~~~~~~~~~~ | |||
| User API Changes | |||
There was a problem hiding this comment.
IIUC this is accurate, but also alot of words: Goal, Option and BUILD syntax changes.
| @@ -57,10 +61,6 @@ Refactoring, Improvements, and Tooling | |||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |||
|
|
|||
|
|
|||
| Testing | |||
There was a problem hiding this comment.
I don't get the argument that this is covered by other categories?
There was a problem hiding this comment.
I've never understood what it's meant to be in the first place?
If we make changes to pants.testutil, those go into "Plugin changes".
If we make changes to our own tests, why would that go into a dedicated section rather than "Refactoring"? This changelog is intended for end-users, not as much for us. They don't really care if we refactor some tests more than they'd care about refactoring production code. No need for special attention.
There was a problem hiding this comment.
I think it's good to call out testing improvements, such as adding tests. Many changes don't affect end-users directly, but they still need to be in some category or another.
There was a problem hiding this comment.
Many changes don't affect end-users directly, but they still need to be in some category or another.
Which is why we have the "Refactoring, Internal Tooling" category. I'm not sure why changes to tests deserve to be elevated over changes to production code and over changes to our build process/CI? From an end-user perspective, they are all "internal changes" to Pants that make the project better, without directly impacting the user.
To be pedantic, if we kept "Testing", I think we would want to split out "Internal changes" into something like "Test internal changes", "Production internal change", and "Build process internal change". Which I suspect we'd agree we don't want to do; that's overspecified for a changelog.
There was a problem hiding this comment.
+1 I think a changelog is fundamentally for users. Iff you decide to log every change, then you're forced to split to 2 lists, user facing and not. You may decide to split user facing further. It doesn't make sense to split not user facing further (nor does it make much sense to include non user facing at all - that's what a git log is for).
There was a problem hiding this comment.
I'm fine omitting internal-only changes entirely from the changelog.
There was a problem hiding this comment.
I think I'm okay with that, too. Our changelogs are long and I can imagine it being overwhelming upgrading across stable releases.
[ci skip-rust] [ci skip-build-wheels]
Now that users are starting to write plugins, we need to start putting changes to the Plugin API in the "API changes" section, rather than "Refactoring".
But, unless you're writing plugins, these changes are irrelevant. So, we differentiate between changes that impact every user—like deprecating options—vs. plugin changes.
We also remove both "testing" and "refactoring" from the changelog. Our changelogs are extremely long, and by definition, users don't need to know about internal-only changes. They can use
git logif they want to see everything.[ci skip-rust]
[ci skip-build-wheels]