Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
---
CC: George Dunlap <George.Dunlap@eu.citrix.com>
CC: Jan Beulich <JBeulich@suse.com>
CC: Stefano Stabellini <sstabellini@kernel.org>
CC: Wei Liu <wl@xen.org>
CC: Julien Grall <julien@xen.org>
CC: Henry Wang <Henry.Wang@arm.com>

A reminder to everyone, write the changelog as it happens, rather than
scrambling to remember 8 months of development just as the release is
happening.
---
 CHANGELOG.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 675413971360..b116163b62c5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ## [unstable UNRELEASED](https://xenbits.xen.org/gitweb/?p=xen.git;a=shortlog;h=staging) - TBD
 
+### Added
+ - On x86, support for features new in Intel Sapphire Rapids CPUs:
+   - PKS (Protection Key Supervisor) available to HVM/PVH guests.
+   - VM-Notify used by Xen to mitigate certain micro-architectural pipeline
+     livelocks, instead of crashing the entire server.
+   - Bus-lock detection, used by Xen to mitigate (by rate-limiting) the system
+     wide impact of a guest misusing atomic instructions.
+
 ## [4.17.0](https://xenbits.xen.org/gitweb/?p=xen.git;a=shortlog;h=RELEASE-4.17.0) - 2022-12-12
 
 ### Changed
-- 
2.11.0

Hi Andrew,

> -----Original Message-----
> From: Andrew Cooper <andrew.cooper3@citrix.com>
> Subject: [PATCH] Changelog: Add details about new features for SPR
> 
> Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>

Thanks for remembering this :)

Acked-by: Henry Wang <Henry.Wang@arm.com>

> ---
> A reminder to everyone, write the changelog as it happens, rather than
> scrambling to remember 8 months of development just as the release is
> happening.

I wonder if there is a way to automate this in our CI so we can avoid
forgetting this. But currently I am not really sure if the solution in my mind
is simple enough... I will try to keep this issue in my mind so that probably I
can come back with some solutions.

Kind regards,
Henry

On 27/01/2023 11:40 am, Henry Wang wrote:
> Hi Andrew,
>
>> -----Original Message-----
>> From: Andrew Cooper <andrew.cooper3@citrix.com>
>> Subject: [PATCH] Changelog: Add details about new features for SPR
>>
>> Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
> Thanks for remembering this :)
>
> Acked-by: Henry Wang <Henry.Wang@arm.com>

Thanks.

I'll commit this when OSSTest has become unblocked.

>
>> ---
>> A reminder to everyone, write the changelog as it happens, rather than
>> scrambling to remember 8 months of development just as the release is
>> happening.
> I wonder if there is a way to automate this in our CI so we can avoid
> forgetting this. But currently I am not really sure if the solution in my mind
> is simple enough... I will try to keep this issue in my mind so that probably I
> can come back with some solutions.

The automated version is `git log $PREV_RELEASE > changelog.log`, and
this is very deliberately not that.

It needs the maintainers / committers to keep "interesting user visible
changes" in mind at some point after the patches have gone in, are
logically complete, and have been around long enough that major
catastrophes (i.e. those liable to incur a full revert) are likely to
have happened.

But I would like to stress.  While it is the Release Maintainer's job to
make sure this gets done, it is not the Release Maintainers job to write
it.  That is an unreasonable burden.

~Andrew

On Mon, Jan 30, 2023 at 3:54 PM Andrew Cooper <amc96@srcf.net> wrote:

> On 27/01/2023 11:40 am, Henry Wang wrote:
> > Hi Andrew,
> >
> >> -----Original Message-----
> >> From: Andrew Cooper <andrew.cooper3@citrix.com>
> >> Subject: [PATCH] Changelog: Add details about new features for SPR
> >>
> >> Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
> > Thanks for remembering this :)
> >
> > Acked-by: Henry Wang <Henry.Wang@arm.com>
>
> Thanks.
>
> I'll commit this when OSSTest has become unblocked.
>
> >
> >> ---
> >> A reminder to everyone, write the changelog as it happens, rather than
> >> scrambling to remember 8 months of development just as the release is
> >> happening.
> > I wonder if there is a way to automate this in our CI so we can avoid
> > forgetting this. But currently I am not really sure if the solution in
> my mind
> > is simple enough... I will try to keep this issue in my mind so that
> probably I
> > can come back with some solutions.
>
> The automated version is `git log $PREV_RELEASE > changelog.log`, and
> this is very deliberately not that.
>
> It needs the maintainers / committers to keep "interesting user visible
> changes" in mind at some point after the patches have gone in, are
> logically complete, and have been around long enough that major
> catastrophes (i.e. those liable to incur a full revert) are likely to
> have happened.
>
> But I would like to stress.  While it is the Release Maintainer's job to
> make sure this gets done, it is not the Release Maintainers job to write
> it.  That is an unreasonable burden.
>

One approach would be to have someone / something (either the release
manager, or an automated script) periodically (monthly?  Bi-weekly?) email
each maintainer a list of the commits under their remit, with an
encouragement to consider what entries could be added to CHANGELOG.md.
i.e., something like this:

8<---
Dear $MAINTAINER_NAME,

During the last $TIME_PERIOD, the commits below have been checked into the
tree which modify code under your maintainership.  Please ensure that
necessary changes to CHANGELOG.md have also been comitted.

Thanks,
 $SENDER

$GIT_LOG
---->8

Ideally this would prompt maintainers to get into the habit of always
asking for CHANGELOG entries to be added during review (which would also
get developers into the habit of always including them); at which point the
maintainers could just skim the commits in the email and only add he odd
CHANGELOG that they may have forgotten.

Thoughts?

 -George

Hi George,

> From: George Dunlap <george.dunlap@cloud.com>
> Subject: Re: [PATCH] Changelog: Add details about new features for SPR
>
> One approach would be to have someone / something (either the release manager, or an automated script)

An automated script would be best if possible IMHO, as the email
content would be pretty much fixed/predictable and the email is
sent periodically.

> periodically (monthly?  Bi-weekly?) email each maintainer a list of the commits under their remit, with an encouragement to consider what entries could be added to CHANGELOG.md.  i.e., something like this:
>
> 8<---
> Dear $MAINTAINER_NAME,
>
> During the last $TIME_PERIOD, the commits below have been checked into the tree which modify code under your maintainership.  Please ensure that necessary changes to CHANGELOG.md have also been comitted.
>
> Thanks,
> $SENDER
>
> $GIT_LOG
> ---->8
>
> Ideally this would prompt maintainers to get into the habit of always asking for CHANGELOG entries to be added during review (which would also get developers into the habit of always including them); at which point the maintainers could just skim the commits in the email and only add he odd CHANGELOG that they may have forgotten.
>
> Thoughts?

I like this idea very much :) Just a small question: As a developer, it is
not really clear to me that under what criteria would a patch/series
deserve for a changelog entry. Personally I would try to include the
CHANGELOG into my changes in the future if this criteria is cleared.

Kind regards,
Henry

>
>  -George

On Thu, Feb 2, 2023 at 2:05 AM Henry Wang <Henry.Wang@arm.com> wrote:

> Hi George,
>
>
>
> > From: George Dunlap <george.dunlap@cloud.com>
>
> > Subject: Re: [PATCH] Changelog: Add details about new features for SPR
>
> >
>
> > One approach would be to have someone / something (either the release
> manager, or an automated script)
>
>
>
> An automated script would be best if possible IMHO, as the email
>
> content would be pretty much fixed/predictable and the email is
>
> sent periodically.
>
>
>
> > periodically (monthly?  Bi-weekly?) email each maintainer a list of the
> commits under their remit, with an encouragement to consider what entries
> could be added to CHANGELOG.md.  i.e., something like this:
>
> >
>
> > 8<---
>
> > Dear $MAINTAINER_NAME,
>
> >
>
> > During the last $TIME_PERIOD, the commits below have been checked into
> the tree which modify code under your maintainership.  Please ensure that
> necessary changes to CHANGELOG.md have also been comitted.
>
> >
>
> > Thanks,
>
> > $SENDER
>
> >
>
> > $GIT_LOG
>
> > ---->8
>
> >
>
> > Ideally this would prompt maintainers to get into the habit of always
> asking for CHANGELOG entries to be added during review (which would also
> get developers into the habit of always including them); at which point the
> maintainers could just skim the commits in the email and only add he odd
> CHANGELOG that they may have forgotten.
>
> >
>
> > Thoughts?
>
>
>
> I like this idea very much :) Just a small question: As a developer, it is
>
> not really clear to me that under what criteria would a patch/series
>
> deserve for a changelog entry. Personally I would try to include the
>
> CHANGELOG into my changes in the future if this criteria is cleared.
>

What I would personally like to see is something that can create a document
like this:

https://go.dev/doc/go1.20

I'm not sure exactly how to quantify that level of description; nor exactly
what other people have in mind.

 -George

>