release notes file

classic Classic list List threaded Threaded
34 messages Options
12
Reply | Threaded
Open this post in threaded view
|

release notes file

Mark Johnston-2
Hi,

Today we add a Relnotes tag to commits that warrant a release note.
My impression is that it doesn't work so well: if a committer forgets
or doesn't know to add one there's no way to amend the commit message
(same for MFCs), and a commit message isn't a convenient place to write
the text of a release note.  I would like to propose adding a top-level
RELNOTES file instead, which like UPDATING would document notes for
specific commits.  It would be truncated every time the head branch is
forked, and changes to it would be MFCed.  This fixes the
above-mentioned problems and would hopefully reduce the amount of time
needed by re@ to compile release notes.

For example:

Index: RELNOTES
===================================================================
--- RELNOTES (nonexistent)
+++ RELNOTES (working copy)
@@ -0,0 +1,8 @@
+Release notes for FreeBSD 13.0.
+
+r349286:
+ swapon(8) can now erase a swap device immediately before
+ enabling it, similar to newfs(8)'s -E option.  This behaviour
+ can be specified by adding -E to swapon(8)'s command-line
+ parameters, or by adding the "trimonce" option to a swap
+ device's /etc/fstab entry.

What do folks think?
_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-hackers
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: release notes file

Warner Losh
I love it. I proposed something similar before, and it went nowhere. I
often forget, or realize after the fact that something should be in the
release notes.


Warner

On Sun, Jun 23, 2019 at 1:21 PM Mark Johnston <[hidden email]> wrote:

> Hi,
>
> Today we add a Relnotes tag to commits that warrant a release note.
> My impression is that it doesn't work so well: if a committer forgets
> or doesn't know to add one there's no way to amend the commit message
> (same for MFCs), and a commit message isn't a convenient place to write
> the text of a release note.  I would like to propose adding a top-level
> RELNOTES file instead, which like UPDATING would document notes for
> specific commits.  It would be truncated every time the head branch is
> forked, and changes to it would be MFCed.  This fixes the
> above-mentioned problems and would hopefully reduce the amount of time
> needed by re@ to compile release notes.
>
> For example:
>
> Index: RELNOTES
> ===================================================================
> --- RELNOTES    (nonexistent)
> +++ RELNOTES    (working copy)
> @@ -0,0 +1,8 @@
> +Release notes for FreeBSD 13.0.
> +
> +r349286:
> +       swapon(8) can now erase a swap device immediately before
> +       enabling it, similar to newfs(8)'s -E option.  This behaviour
> +       can be specified by adding -E to swapon(8)'s command-line
> +       parameters, or by adding the "trimonce" option to a swap
> +       device's /etc/fstab entry.
>
> What do folks think?
> _______________________________________________
> [hidden email] mailing list
> https://lists.freebsd.org/mailman/listinfo/freebsd-hackers
> To unsubscribe, send any mail to "[hidden email]"
>
_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-hackers
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: release notes file

Ian Lepore-3
In reply to this post by Mark Johnston-2
On Sun, 2019-06-23 at 15:18 -0400, Mark Johnston wrote:

> Hi,
>
> Today we add a Relnotes tag to commits that warrant a release note.
> My impression is that it doesn't work so well: if a committer forgets
> or doesn't know to add one there's no way to amend the commit message
> (same for MFCs), and a commit message isn't a convenient place to
> write
> the text of a release note.  I would like to propose adding a top-
> level
> RELNOTES file instead, which like UPDATING would document notes for
> specific commits.  It would be truncated every time the head branch
> is
> forked, and changes to it would be MFCed.  This fixes the
> above-mentioned problems and would hopefully reduce the amount of
> time
> needed by re@ to compile release notes.
>
> For example:
>
> Index: RELNOTES
> ===================================================================
> --- RELNOTES (nonexistent)
> +++ RELNOTES (working copy)
> @@ -0,0 +1,8 @@
> +Release notes for FreeBSD 13.0.
> +
> +r349286:
> + swapon(8) can now erase a swap device immediately before
> + enabling it, similar to newfs(8)'s -E option.  This behaviour
> + can be specified by adding -E to swapon(8)'s command-line
> + parameters, or by adding the "trimonce" option to a swap
> + device's /etc/fstab entry.
>
> What do folks think?
>

I think it's a very good idea.

-- Ian

_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-hackers
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: release notes file

Glen Barber-6
In reply to this post by Mark Johnston-2
Yes, please.

Glen
Sent from my phone.
Please excuse my brevity and/or typos.

> On Jun 23, 2019, at 3:18 PM, Mark Johnston <[hidden email]> wrote:
>
> Hi,
>
> Today we add a Relnotes tag to commits that warrant a release note.
> My impression is that it doesn't work so well: if a committer forgets
> or doesn't know to add one there's no way to amend the commit message
> (same for MFCs), and a commit message isn't a convenient place to write
> the text of a release note.  I would like to propose adding a top-level
> RELNOTES file instead, which like UPDATING would document notes for
> specific commits.  It would be truncated every time the head branch is
> forked, and changes to it would be MFCed.  This fixes the
> above-mentioned problems and would hopefully reduce the amount of time
> needed by re@ to compile release notes.
>
> For example:
>
> Index: RELNOTES
> ===================================================================
> --- RELNOTES    (nonexistent)
> +++ RELNOTES    (working copy)
> @@ -0,0 +1,8 @@
> +Release notes for FreeBSD 13.0.
> +
> +r349286:
> +    swapon(8) can now erase a swap device immediately before
> +    enabling it, similar to newfs(8)'s -E option.  This behaviour
> +    can be specified by adding -E to swapon(8)'s command-line
> +    parameters, or by adding the "trimonce" option to a swap
> +    device's /etc/fstab entry.
>
> What do folks think?
>
_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-hackers
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: release notes file

Glen Barber-6
FWIW, I don’t think “either/or” is necessarily the best approach; meaning I would like to still keep the tag in the default template.

Glen
(Who knows first hand how much it sucks going through commit logs for relnotes entries)
Sent from my phone.
Please excuse my brevity and/or typos.

> On Jun 23, 2019, at 3:49 PM, Glen Barber <[hidden email]> wrote:
>
> Yes, please.
>
> Glen
> Sent from my phone.
> Please excuse my brevity and/or typos.
>
>> On Jun 23, 2019, at 3:18 PM, Mark Johnston <[hidden email]> wrote:
>>
>> Hi,
>>
>> Today we add a Relnotes tag to commits that warrant a release note.
>> My impression is that it doesn't work so well: if a committer forgets
>> or doesn't know to add one there's no way to amend the commit message
>> (same for MFCs), and a commit message isn't a convenient place to write
>> the text of a release note.  I would like to propose adding a top-level
>> RELNOTES file instead, which like UPDATING would document notes for
>> specific commits.  It would be truncated every time the head branch is
>> forked, and changes to it would be MFCed.  This fixes the
>> above-mentioned problems and would hopefully reduce the amount of time
>> needed by re@ to compile release notes.
>>
>> For example:
>>
>> Index: RELNOTES
>> ===================================================================
>> --- RELNOTES    (nonexistent)
>> +++ RELNOTES    (working copy)
>> @@ -0,0 +1,8 @@
>> +Release notes for FreeBSD 13.0.
>> +
>> +r349286:
>> +    swapon(8) can now erase a swap device immediately before
>> +    enabling it, similar to newfs(8)'s -E option.  This behaviour
>> +    can be specified by adding -E to swapon(8)'s command-line
>> +    parameters, or by adding the "trimonce" option to a swap
>> +    device's /etc/fstab entry.
>>
>> What do folks think?
>>
>

_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-hackers
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: release notes file

Warner Losh
On Sun, Jun 23, 2019 at 1:56 PM Glen Barber <[hidden email]> wrote:

> FWIW, I don’t think “either/or” is necessarily the best approach; meaning
> I would like to still keep the tag in the default template.
>

A while ago, I proposed a protocol that we'd only have the RELNOTES file.

The other part of the protocol was to remove it from RELNOTES once it was
added to the release notes. This way, we can have multiple people working
on the release notes should we be so fortunate to have those resources in
the future. It's minorly racy, but not terrible. This way, release notes
text could also be written by the committer and tweaked by whomever
compiles the release notes.

However, I'm cool with having it in the commit message + template since
it's better to have a heads up you need to write something than not. The
understanding would be a RelNotes: yes would mean that someone else would
write the notes and if you wanted to have more control over what went out,
you'd use RELNOTES.

Glen, do you think that's a workable protocol?

Warner


> Glen
> (Who knows first hand how much it sucks going through commit logs for
> relnotes entries)
> Sent from my phone.
> Please excuse my brevity and/or typos.
>
> > On Jun 23, 2019, at 3:49 PM, Glen Barber <[hidden email]> wrote:
> >
> > Yes, please.
> >
> > Glen
> > Sent from my phone.
> > Please excuse my brevity and/or typos.
> >
> >> On Jun 23, 2019, at 3:18 PM, Mark Johnston <[hidden email]> wrote:
> >>
> >> Hi,
> >>
> >> Today we add a Relnotes tag to commits that warrant a release note.
> >> My impression is that it doesn't work so well: if a committer forgets
> >> or doesn't know to add one there's no way to amend the commit message
> >> (same for MFCs), and a commit message isn't a convenient place to write
> >> the text of a release note.  I would like to propose adding a top-level
> >> RELNOTES file instead, which like UPDATING would document notes for
> >> specific commits.  It would be truncated every time the head branch is
> >> forked, and changes to it would be MFCed.  This fixes the
> >> above-mentioned problems and would hopefully reduce the amount of time
> >> needed by re@ to compile release notes.
> >>
> >> For example:
> >>
> >> Index: RELNOTES
> >> ===================================================================
> >> --- RELNOTES    (nonexistent)
> >> +++ RELNOTES    (working copy)
> >> @@ -0,0 +1,8 @@
> >> +Release notes for FreeBSD 13.0.
> >> +
> >> +r349286:
> >> +    swapon(8) can now erase a swap device immediately before
> >> +    enabling it, similar to newfs(8)'s -E option.  This behaviour
> >> +    can be specified by adding -E to swapon(8)'s command-line
> >> +    parameters, or by adding the "trimonce" option to a swap
> >> +    device's /etc/fstab entry.
> >>
> >> What do folks think?
> >>
> >
>
> _______________________________________________
> [hidden email] mailing list
> https://lists.freebsd.org/mailman/listinfo/freebsd-hackers
> To unsubscribe, send any mail to "[hidden email]"
>
_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-hackers
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: release notes file

Glen Barber-6
On Sun, Jun 23, 2019 at 02:01:31PM -0600, Warner Losh wrote:

> On Sun, Jun 23, 2019 at 1:56 PM Glen Barber <[hidden email]> wrote:
>
> > FWIW, I don’t think “either/or” is necessarily the best approach; meaning
> > I would like to still keep the tag in the default template.
> >
>
> A while ago, I proposed a protocol that we'd only have the RELNOTES file.
>
> The other part of the protocol was to remove it from RELNOTES once it was
> added to the release notes. This way, we can have multiple people working
> on the release notes should we be so fortunate to have those resources in
> the future. It's minorly racy, but not terrible. This way, release notes
> text could also be written by the committer and tweaked by whomever
> compiles the release notes.
>
> However, I'm cool with having it in the commit message + template since
> it's better to have a heads up you need to write something than not. The
> understanding would be a RelNotes: yes would mean that someone else would
> write the notes and if you wanted to have more control over what went out,
> you'd use RELNOTES.
>
> Glen, do you think that's a workable protocol?
>
It's kind of difficult for me to put the words together that effectively
conveys what I'm thinking or where my mindset is here, but I'll try.

I am in full support of a RELNOTES file, but I think that should be
supplementary to the 'Relnotes: yes' (or other variations of a non-empty
tag).

I am conflicted on removing entries from a RELNOTES file once they are
added to the release notes, because that might be a more convenient way
for end users to get an idea of what changed.  However, "Relnotes: yes"
does not solve this for those folks.

It is easy to truncate the file when a new branch is created, just as
a workflow example, but I think the larger thing here is that while
there are folks that commit something without "Relnotes: yes" because
they forgot (or it did not occur to them at the time that it is
a user-visible change), it can be equally difficult to remember to
update a file specifically dedicated to this.

All that said, having at least a sample text of what to include would be
extremely helpful, at least for me, as sometimes I have to ping
committers out-of-band to understand why a particular commit was flagged
as "Relnotes: yes".

Hopefully all that made sense.  :)

Glen


signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: release notes file

Mark Johnston-2
On Sun, Jun 23, 2019 at 08:19:43PM +0000, Glen Barber wrote:

> On Sun, Jun 23, 2019 at 02:01:31PM -0600, Warner Losh wrote:
> > On Sun, Jun 23, 2019 at 1:56 PM Glen Barber <[hidden email]> wrote:
> >
> > > FWIW, I don’t think “either/or” is necessarily the best approach; meaning
> > > I would like to still keep the tag in the default template.
> > >
> >
> > A while ago, I proposed a protocol that we'd only have the RELNOTES file.
> >
> > The other part of the protocol was to remove it from RELNOTES once it was
> > added to the release notes. This way, we can have multiple people working
> > on the release notes should we be so fortunate to have those resources in
> > the future. It's minorly racy, but not terrible. This way, release notes
> > text could also be written by the committer and tweaked by whomever
> > compiles the release notes.
> >
> > However, I'm cool with having it in the commit message + template since
> > it's better to have a heads up you need to write something than not. The
> > understanding would be a RelNotes: yes would mean that someone else would
> > write the notes and if you wanted to have more control over what went out,
> > you'd use RELNOTES.
> >
> > Glen, do you think that's a workable protocol?
> >
>
> It's kind of difficult for me to put the words together that effectively
> conveys what I'm thinking or where my mindset is here, but I'll try.
>
> I am in full support of a RELNOTES file, but I think that should be
> supplementary to the 'Relnotes: yes' (or other variations of a non-empty
> tag).
>
> I am conflicted on removing entries from a RELNOTES file once they are
> added to the release notes, because that might be a more convenient way
> for end users to get an idea of what changed.  However, "Relnotes: yes"
> does not solve this for those folks.
>
> It is easy to truncate the file when a new branch is created, just as
> a workflow example, but I think the larger thing here is that while
> there are folks that commit something without "Relnotes: yes" because
> they forgot (or it did not occur to them at the time that it is
> a user-visible change), it can be equally difficult to remember to
> update a file specifically dedicated to this.
>
> All that said, having at least a sample text of what to include would be
> extremely helpful, at least for me, as sometimes I have to ping
> committers out-of-band to understand why a particular commit was flagged
> as "Relnotes: yes".
>
> Hopefully all that made sense.  :)

It makes sense to me.  I think the idea is that "Relnotes: yes" is
advisory and serves as a reminder that the commit should get a release
note; committers may forget or not want to write RELNOTES entries for
some reason.  Similar to how "MFC after" is advisory and doesn't
guarantee that an MFC has been done after any particular point.  re@
would need to scan commits for Relnotes tags that don't have entries in
RELNOTES.  Since RELNOTES can be updated after the fact, this set
would hopefully be small.

Regarding whether RELNOTES entries should be removed, I would prefer to
keep them at least until head is branched.  They would serve as useful
documentation to users, and if there are multiple people compiling
release notes they can synchronize in other ways.  At least, I would
wait for it to become a problem before trying to solve it by removing
entries from RELNOTES.
_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-hackers
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: release notes file

Oliver Pinter-4
In reply to this post by Mark Johnston-2
On Sunday, June 23, 2019, Mark Johnston <[hidden email]> wrote:

> Hi,
>
> Today we add a Relnotes tag to commits that warrant a release note.
> My impression is that it doesn't work so well: if a committer forgets
> or doesn't know to add one there's no way to amend the commit message
> (same for MFCs), and a commit message isn't a convenient place to write
> the text of a release note.  I would like to propose adding a top-level
> RELNOTES file instead, which like UPDATING would document notes for
> specific commits.  It would be truncated every time the head branch is
> forked, and changes to it would be MFCed.  This fixes the
> above-mentioned problems and would hopefully reduce the amount of time
> needed by re@ to compile release notes.



In the future with git you could easily add meta infos for specific
commits. The project currently using this to store git-svn meta, but you
can add more the one note to each commit.
W




>
> For example:
>
> Index: RELNOTES
> ===================================================================
> --- RELNOTES    (nonexistent)
> +++ RELNOTES    (working copy)
> @@ -0,0 +1,8 @@
> +Release notes for FreeBSD 13.0.
> +
> +r349286:
> +       swapon(8) can now erase a swap device immediately before
> +       enabling it, similar to newfs(8)'s -E option.  This behaviour
> +       can be specified by adding -E to swapon(8)'s command-line
> +       parameters, or by adding the "trimonce" option to a swap
> +       device's /etc/fstab entry.
>
> What do folks think?
> _______________________________________________
> [hidden email] mailing list
> https://lists.freebsd.org/mailman/listinfo/freebsd-hackers
> To unsubscribe, send any mail to "[hidden email]"
>
_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-hackers
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: release notes file

Glen Barber-6
In reply to this post by Mark Johnston-2
On Sun, Jun 23, 2019 at 05:09:59PM -0400, Mark Johnston wrote:

> On Sun, Jun 23, 2019 at 08:19:43PM +0000, Glen Barber wrote:
> > On Sun, Jun 23, 2019 at 02:01:31PM -0600, Warner Losh wrote:
> > > On Sun, Jun 23, 2019 at 1:56 PM Glen Barber <[hidden email]> wrote:
> > >
> > > > FWIW, I don’t think “either/or” is necessarily the best approach; meaning
> > > > I would like to still keep the tag in the default template.
> > > >
> > >
> > > A while ago, I proposed a protocol that we'd only have the RELNOTES file.
> > >
> > > The other part of the protocol was to remove it from RELNOTES once it was
> > > added to the release notes. This way, we can have multiple people working
> > > on the release notes should we be so fortunate to have those resources in
> > > the future. It's minorly racy, but not terrible. This way, release notes
> > > text could also be written by the committer and tweaked by whomever
> > > compiles the release notes.
> > >
> > > However, I'm cool with having it in the commit message + template since
> > > it's better to have a heads up you need to write something than not. The
> > > understanding would be a RelNotes: yes would mean that someone else would
> > > write the notes and if you wanted to have more control over what went out,
> > > you'd use RELNOTES.
> > >
> > > Glen, do you think that's a workable protocol?
> > >
> >
> > It's kind of difficult for me to put the words together that effectively
> > conveys what I'm thinking or where my mindset is here, but I'll try.
> >
> > I am in full support of a RELNOTES file, but I think that should be
> > supplementary to the 'Relnotes: yes' (or other variations of a non-empty
> > tag).
> >
> > I am conflicted on removing entries from a RELNOTES file once they are
> > added to the release notes, because that might be a more convenient way
> > for end users to get an idea of what changed.  However, "Relnotes: yes"
> > does not solve this for those folks.
> >
> > It is easy to truncate the file when a new branch is created, just as
> > a workflow example, but I think the larger thing here is that while
> > there are folks that commit something without "Relnotes: yes" because
> > they forgot (or it did not occur to them at the time that it is
> > a user-visible change), it can be equally difficult to remember to
> > update a file specifically dedicated to this.
> >
> > All that said, having at least a sample text of what to include would be
> > extremely helpful, at least for me, as sometimes I have to ping
> > committers out-of-band to understand why a particular commit was flagged
> > as "Relnotes: yes".
> >
> > Hopefully all that made sense.  :)
>
> It makes sense to me.  I think the idea is that "Relnotes: yes" is
> advisory and serves as a reminder that the commit should get a release
> note; committers may forget or not want to write RELNOTES entries for
> some reason.  Similar to how "MFC after" is advisory and doesn't
> guarantee that an MFC has been done after any particular point.  re@
> would need to scan commits for Relnotes tags that don't have entries in
> RELNOTES.  Since RELNOTES can be updated after the fact, this set
> would hopefully be small.
>
> Regarding whether RELNOTES entries should be removed, I would prefer to
> keep them at least until head is branched.  They would serve as useful
> documentation to users, and if there are multiple people compiling
> release notes they can synchronize in other ways.  At least, I would
> wait for it to become a problem before trying to solve it by removing
> entries from RELNOTES.
>
To your latter point, removing the RELNOTES entries, this is what I sort
of had in mind:

 head -> stable/X -> releng/X.Y:
  head/RELNOTES gets truncated after stable/X is created;
  stable/X gets truncated after releng/X.Y is created

For point releases, the workflow is similar as it just excludes head:
 stable/X -> releng/X.Y:
  stable/X gets truncated after releng/X.Y is created

In other words, there would be no arbitrarily-long file, but there
would potentially be some overlap for a major release where a dot-zero
release has last-minute new stuff that should be in release notes; it
would grow and shrink as development happens.

Or, this is how I see it being most beneficial to RE when it comes to
writing release notes, at least.

Glen


signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: release notes file

Mark Johnston-2
On Sun, Jun 23, 2019 at 09:57:29PM +0000, Glen Barber wrote:

> On Sun, Jun 23, 2019 at 05:09:59PM -0400, Mark Johnston wrote:
> > Regarding whether RELNOTES entries should be removed, I would prefer to
> > keep them at least until head is branched.  They would serve as useful
> > documentation to users, and if there are multiple people compiling
> > release notes they can synchronize in other ways.  At least, I would
> > wait for it to become a problem before trying to solve it by removing
> > entries from RELNOTES.
> >
>
> To your latter point, removing the RELNOTES entries, this is what I sort
> of had in mind:
>
>  head -> stable/X -> releng/X.Y:
>   head/RELNOTES gets truncated after stable/X is created;
>   stable/X gets truncated after releng/X.Y is created
>
> For point releases, the workflow is similar as it just excludes head:
>  stable/X -> releng/X.Y:
>   stable/X gets truncated after releng/X.Y is created
>
> In other words, there would be no arbitrarily-long file, but there
> would potentially be some overlap for a major release where a dot-zero
> release has last-minute new stuff that should be in release notes; it
> would grow and shrink as development happens.
>
> Or, this is how I see it being most beneficial to RE when it comes to
> writing release notes, at least.

This is what I had pictured as well.
_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-hackers
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: release notes file

Bjoern A. Zeeb-2
In reply to this post by Mark Johnston-2
On 23 Jun 2019, at 19:18, Mark Johnston wrote:

Hi,

> Today we add a Relnotes tag to commits that warrant a release note.
> My impression is that it doesn't work so well: if a committer forgets
> or doesn't know to add one there's no way to amend the commit message
> (same for MFCs), and a commit message isn't a convenient place to
> write
> the text of a release note.  I would like to propose adding a
> top-level
> RELNOTES file instead, which like UPDATING would document notes for
> specific commits.  It would be truncated every time the head branch is
> forked, and changes to it would be MFCed.  This fixes the
> above-mentioned problems and would hopefully reduce the amount of time
> needed by re@ to compile release notes.

Hooray.  Can we put that file into the doc repo, so that the ports
people, and the docs people, and all other kinds of hats can put things
in there as well?

Oh, the release notes go into the doc repo anyway.  Can we just put them
in the right place and just fill them from a skeleton where they should
be and naturally grow the document (feel free to use a different markup
language once doc is ready for that).

Oh, with that release notes are written automatically and you are still
responsible for that your stuff is in there.  And the release notes only
need an editing pass in the end?

And the wiki pages like “What’s cooking for 13?” or similar could
just vanish as we’d have these updated at least every 10 minutes
automatically .. on our web server under /releases/ where they belong ..

How amazing would that be?


/bz
_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-hackers
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: release notes file

Glen Barber-6
On Sun, Jun 23, 2019 at 11:23:57PM +0000, Bjoern A. Zeeb wrote:

> On 23 Jun 2019, at 19:18, Mark Johnston wrote:
>
> Hi,
>
> > Today we add a Relnotes tag to commits that warrant a release note.
> > My impression is that it doesn't work so well: if a committer forgets
> > or doesn't know to add one there's no way to amend the commit message
> > (same for MFCs), and a commit message isn't a convenient place to write
> > the text of a release note.  I would like to propose adding a top-level
> > RELNOTES file instead, which like UPDATING would document notes for
> > specific commits.  It would be truncated every time the head branch is
> > forked, and changes to it would be MFCed.  This fixes the
> > above-mentioned problems and would hopefully reduce the amount of time
> > needed by re@ to compile release notes.
>
> Hooray.  Can we put that file into the doc repo, so that the ports people,
> and the docs people, and all other kinds of hats can put things in there as
> well?
>
> Oh, the release notes go into the doc repo anyway.  Can we just put them in
> the right place and just fill them from a skeleton where they should be and
> naturally grow the document (feel free to use a different markup language
> once doc is ready for that).
>
> Oh, with that release notes are written automatically and you are still
> responsible for that your stuff is in there.  And the release notes only
> need an editing pass in the end?
>
> And the wiki pages like “What’s cooking for 13?” or similar could just
> vanish as we’d have these updated at least every 10 minutes automatically ..
> on our web server under /releases/ where they belong ..
>
> How amazing would that be?
Very.

But, I have one non-important nit -- the file in question does not need
to be formatted for the documentation language of the day.  In other
words, I do not see this file as a "copy/paste from here to there and be
done with it" sort of thing; i.e., grammar nits, clarifications that
stray from the original commit log (or commit log intent), etc.

When re@ requests clarification on commits or prods committers for
things that may not have otherwise made it into the release notes, it
isn't sent as a "please send us the properly-formatted XML entry" or
some such thing, so personally, I am perfectly fine with a 80-character
line-length raw plain-text entry.

Just my $0.02 USD.

Glen


signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: release notes file

Mark Johnston-2
In reply to this post by Bjoern A. Zeeb-2
On Sun, Jun 23, 2019 at 11:23:57PM +0000, Bjoern A. Zeeb wrote:

> On 23 Jun 2019, at 19:18, Mark Johnston wrote:
>
> Hi,
>
> > Today we add a Relnotes tag to commits that warrant a release note.
> > My impression is that it doesn't work so well: if a committer forgets
> > or doesn't know to add one there's no way to amend the commit message
> > (same for MFCs), and a commit message isn't a convenient place to
> > write
> > the text of a release note.  I would like to propose adding a
> > top-level
> > RELNOTES file instead, which like UPDATING would document notes for
> > specific commits.  It would be truncated every time the head branch is
> > forked, and changes to it would be MFCed.  This fixes the
> > above-mentioned problems and would hopefully reduce the amount of time
> > needed by re@ to compile release notes.
>
> Hooray.  Can we put that file into the doc repo, so that the ports
> people, and the docs people, and all other kinds of hats can put things
> in there as well?

Virtually all of the 12.0 release notes are for src/ (there are 4 lines
for ports/pkg and 1 line for docs, and the latter describes a new man
page in src).  Why is it important to have a single place for everyone
to commit their entries?

> Oh, the release notes go into the doc repo anyway.  Can we just put them
> in the right place and just fill them from a skeleton where they should
> be and naturally grow the document (feel free to use a different markup
> language once doc is ready for that).
>
> Oh, with that release notes are written automatically and you are still
> responsible for that your stuff is in there.  And the release notes only
> need an editing pass in the end?
>
> And the wiki pages like “What’s cooking for 13?” or similar could
> just vanish as we’d have these updated at least every 10 minutes
> automatically .. on our web server under /releases/ where they belong ..
>
> How amazing would that be?

I would guess that many src committers simply won't add release notes if
they have to commit to a second repository and use some unfamiliar
markup format and worry about validating the file.  There are lots of
__FreeBSD_version bumps that go undocumented until someone else goes in
and fills in the missing entries.  A plain-text file in src repo for src
release notes is low-friction and creates only marginally more work for
RE.  "What's cooking for 13?" can just point to the copy of RELNOTES in
svnweb.

That said, I personally would try to commit my release notes to a doc
repo file if one existed.  I've spent a few minutes trying to compile
the 12.0 notes on my desktop and have not been able to get past, "cannot
parse http://www.FreeBSD.org/XML/share/xml/freebsd-xhtml-release.xsl".
So, I'm probably not a good person to set up release notes for 13.0.  I
will help fill in entries for commits since the 12.0 if someone else
does that setup.
_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-hackers
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: release notes file

Rodney W. Grimes-6
In reply to this post by Glen Barber-6
> On Sun, Jun 23, 2019 at 11:23:57PM +0000, Bjoern A. Zeeb wrote:
> > On 23 Jun 2019, at 19:18, Mark Johnston wrote:
> >
> > Hi,
> >
> > > Today we add a Relnotes tag to commits that warrant a release note.
> > > My impression is that it doesn't work so well: if a committer forgets
> > > or doesn't know to add one there's no way to amend the commit message
> > > (same for MFCs), and a commit message isn't a convenient place to write
> > > the text of a release note.  I would like to propose adding a top-level
> > > RELNOTES file instead, which like UPDATING would document notes for
> > > specific commits.  It would be truncated every time the head branch is
> > > forked, and changes to it would be MFCed.  This fixes the
> > > above-mentioned problems and would hopefully reduce the amount of time
> > > needed by re@ to compile release notes.
> >
> > Hooray.  Can we put that file into the doc repo, so that the ports people,
> > and the docs people, and all other kinds of hats can put things in there as
> > well?

The file needs to live in src/ as this is to catch the missed
Release Notes: Y thing and if you put it in doc repo src committers
have hard access to even make a commit to it.

Ideally some people well want to commit to src/RELNOTES at the
same time as they make there commit to the tree, helping the
release engineering team out a great deal.

For those forgotten Release Notes: Yes items one simple does a
top level sparse checkout of ^/head/base add an entry to RELNOTES
stating what rXXXXXX it applies to and what was left out, can
even be as simple as "Forgot Relnotes: Y".

I was working on a proposal while part of RE to do much of this,
that proposal was shelfed when I exited RE.

> > Oh, the release notes go into the doc repo anyway.  Can we just put them in
> > the right place and just fill them from a skeleton where they should be and
> > naturally grow the document (feel free to use a different markup language
> > once doc is ready for that).
> >
> > Oh, with that release notes are written automatically and you are still
> > responsible for that your stuff is in there.  And the release notes only
> > need an editing pass in the end?
> >
> > And the wiki pages like ?What?s cooking for 13?? or similar could just
> > vanish as we?d have these updated at least every 10 minutes automatically ..
> > on our web server under /releases/ where they belong ..
> >
> > How amazing would that be?
>
> Very.
>
> But, I have one non-important nit -- the file in question does not need
> to be formatted for the documentation language of the day.  In other
> words, I do not see this file as a "copy/paste from here to there and be
> done with it" sort of thing; i.e., grammar nits, clarifications that
> stray from the original commit log (or commit log intent), etc.

That was also my feelings, the file should be extremly simple,
and rough.  It may have 2 or more parts.  It should be possible
to automatic collecting of Relnotes: foo entries from commits and
making sure they all have entries in this file.

The 2 part thing is I had a part that is kinda RE only,
that is where RE tracks and builds the fuller text from the
simple entries added by developers or the releasenotes tag.
The simpler entries are marked off as "processed
by RE (username@) on date" so that they could be worked on
in parallel.  I felt this could be expanded to people outside of RE
once more experienced was gained and operational procedures
established.

Examples:
r123342: Relnotes: Yes forgot to flag in original commit
This is a committer cleaning up a forgotten flag

r123344: Relnotes: Yes added by autobot1 on 2019/06/21
This is the type of thing a weekly cronjob, or even a
postcommit hook script does.

What it looks like after a RE/Doc person deals with it:

r123344: Relnotes: Yes proccess by RE (gjb@) on 2019/06/22
...
PART 2 of file:

r12344: This commit added the new feature reserve parachute
        to appliction pilot ejection.  Please exercise care
        when using it as it is experimental and the riggers
        are still learning to pack properly.

These would be visible to all committers so if someone makes
a mistake discribing a change that is going into release notes
feedback can be provided in very short order.

>
> When re@ requests clarification on commits or prods committers for
> things that may not have otherwise made it into the release notes, it
> isn't sent as a "please send us the properly-formatted XML entry" or
> some such thing, so personally, I am perfectly fine with a 80-character
> line-length raw plain-text entry.

Yep

> Just my $0.02 USD.
> Glen
Here, have some change.... $0.01

--
Rod Grimes                                                 [hidden email]
_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-hackers
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: release notes file

Rodney W. Grimes-6
In reply to this post by Mark Johnston-2
> On Sun, Jun 23, 2019 at 11:23:57PM +0000, Bjoern A. Zeeb wrote:
> > On 23 Jun 2019, at 19:18, Mark Johnston wrote:
> >
> > Hi,
> >
> > > Today we add a Relnotes tag to commits that warrant a release note.
> > > My impression is that it doesn't work so well: if a committer forgets
> > > or doesn't know to add one there's no way to amend the commit message
> > > (same for MFCs), and a commit message isn't a convenient place to
> > > write
> > > the text of a release note.  I would like to propose adding a
> > > top-level
> > > RELNOTES file instead, which like UPDATING would document notes for
> > > specific commits.  It would be truncated every time the head branch is
> > > forked, and changes to it would be MFCed.  This fixes the
> > > above-mentioned problems and would hopefully reduce the amount of time
> > > needed by re@ to compile release notes.
> >
> > Hooray.  Can we put that file into the doc repo, so that the ports
> > people, and the docs people, and all other kinds of hats can put things
> > in there as well?
>
> Virtually all of the 12.0 release notes are for src/ (there are 4 lines
> for ports/pkg and 1 line for docs, and the latter describes a new man
> page in src).  Why is it important to have a single place for everyone
> to commit their entries?

I echo your concerns.

> > Oh, the release notes go into the doc repo anyway.  Can we just put them
> > in the right place and just fill them from a skeleton where they should
> > be and naturally grow the document (feel free to use a different markup
> > language once doc is ready for that).
> >
> > Oh, with that release notes are written automatically and you are still
> > responsible for that your stuff is in there.  And the release notes only
> > need an editing pass in the end?
> >
> > And the wiki pages like ?What?s cooking for 13?? or similar could
> > just vanish as we?d have these updated at least every 10 minutes
> > automatically .. on our web server under /releases/ where they belong ..
> >
> > How amazing would that be?
>
> I would guess that many src committers simply won't add release notes if
> they have to commit to a second repository and use some unfamiliar
> markup format and worry about validating the file.  There are lots of
> __FreeBSD_version bumps that go undocumented until someone else goes in
> and fills in the missing entries.  A plain-text file in src repo for src
> release notes is low-friction and creates only marginally more work for
> RE.  "What's cooking for 13?" can just point to the copy of RELNOTES in
> svnweb.

Very much my position on the issue of a simple text file as
src/RELNOTES, see other reply.

>
> That said, I personally would try to commit my release notes to a doc
> repo file if one existed.  I've spent a few minutes trying to compile
> the 12.0 notes on my desktop and have not been able to get past, "cannot
> parse http://www.FreeBSD.org/XML/share/xml/freebsd-xhtml-release.xsl".
> So, I'm probably not a good person to set up release notes for 13.0.  I
> will help fill in entries for commits since the 12.0 if someone else
> does that setup.

Even having you do the simple text in the RELNOTES file is 90% of the
work, formatting, markdown, whatever, lets let the doc experts deal
with that.  This would be a case where we could consistantly delivery
a fair bit of simple text for them to work on, and it would take work
load off RE@.

--
Rod Grimes                                                 [hidden email]
_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-hackers
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: release notes file

Warner Losh
>
> > That said, I personally would try to commit my release notes to a doc
> > repo file if one existed.  I've spent a few minutes trying to compile
> > the 12.0 notes on my desktop and have not been able to get past, "cannot
> > parse http://www.FreeBSD.org/XML/share/xml/freebsd-xhtml-release.xsl".
> > So, I'm probably not a good person to set up release notes for 13.0.  I
> > will help fill in entries for commits since the 12.0 if someone else
> > does that setup.
>
> Even having you do the simple text in the RELNOTES file is 90% of the
> work, formatting, markdown, whatever, lets let the doc experts deal
> with that.  This would be a case where we could consistantly delivery
> a fair bit of simple text for them to work on, and it would take work
> load off RE@.
>

I'm starting to think that maybe we have one RELNOTES per repo at the top.
It should be the running list of everything, in markdown format in a
stylized format so we can parse it mechanically. No special permissions
needed, no funky language to learn, no tools to install.

We can merge it with a script. We can make sure that all the relnotes: yes
entries in the repo have an entry in RELNOTES via a script (or we could
just add the commit message as a boiler plate via a script automatically
via a cron job that runs daily / weekly).

Then it's all there, and we don't have to keep book in multiple files /
formats / etc. Developers can get an entry in there with a single line, or
they can write their own custom entry if the commit message isn't right.

Tech writers could also word-smith things as we go when they have time so
it's not a huge burden at the end. And people can look along with svnweb /
github (if it's markdown, it will look pretty automatically on github).

And it fits in with the efforts to modernize doc process since it gets
everybody thinking about and contributing content.

Then at release time we parse the markdown file from the 3 repos and
convert it to whatever format doc is using and we're done.

But regardless of the outcome, having it documented in the developer's
handbook would be best.

Warner
_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-hackers
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: release notes file

Rodney W. Grimes-6
> >
> > > That said, I personally would try to commit my release notes to a doc
> > > repo file if one existed.  I've spent a few minutes trying to compile
> > > the 12.0 notes on my desktop and have not been able to get past, "cannot
> > > parse http://www.FreeBSD.org/XML/share/xml/freebsd-xhtml-release.xsl".
> > > So, I'm probably not a good person to set up release notes for 13.0.  I
> > > will help fill in entries for commits since the 12.0 if someone else
> > > does that setup.
> >
> > Even having you do the simple text in the RELNOTES file is 90% of the
> > work, formatting, markdown, whatever, lets let the doc experts deal
> > with that.  This would be a case where we could consistantly delivery
> > a fair bit of simple text for them to work on, and it would take work
> > load off RE@.
> >
>
> I'm starting to think that maybe we have one RELNOTES per repo at the top.
I was only thinking for /usr/src, aka ^/head/base/ to start with, as I do
not know that we generate release notes stuff like this covering the ports
or doc tree, though I certainly agree that the future could expand to those
areas.

> It should be the running list of everything, in markdown format in a
> stylized format so we can parse it mechanically. No special permissions
> needed, no funky language to learn, no tools to install.

Strike markdown, as Both Glen and myself have expressed pure ascii text
just like UPDATING is the path of least resistance.  I might be convinced
of a very very lightweight xml like thing for parsing purposes, ie the
rXXXXXX needs to be locatable.

> We can merge it with a script. We can make sure that all the relnotes: yes
> entries in the repo have an entry in RELNOTES via a script (or we could
> just add the commit message as a boiler plate via a script automatically
> via a cron job that runs daily / weekly).

Yes, but this needs some more though, even just the one liner
I sighted in an earlier reply is fine for an RE@ working on the
notes, but perhaps having the whole commit message added by the automation
might lead to a shorter cycle time in processing them.

>
> Then it's all there, and we don't have to keep book in multiple files /
> formats / etc. Developers can get an entry in there with a single line, or
> they can write their own custom entry if the commit message isn't right.
>
> Tech writers could also word-smith things as we go when they have time so
> it's not a huge burden at the end. And people can look along with svnweb /
> github (if it's markdown, it will look pretty automatically on github).
>
> And it fits in with the efforts to modernize doc process since it gets
> everybody thinking about and contributing content.
>
> Then at release time we parse the markdown file from the 3 repos and
> convert it to whatever format doc is using and we're done.
>
> But regardless of the outcome, having it documented in the developer's
> handbook would be best.

Other than I do not know of any release notes: yes type things that come
from doc/ or ports/ this is all in line with what I had modeled in my
mind and was evolving as I had discussions with Glen about it.  Oh, and
pure simple text files, though as I stated earlier, very light xmlish
tagging might be ok.

Initially I just wanted a way to record the missed Relnotes: Y entires,
as that in itself is a huge step forward in creating more complete
release notes.  The collection of all the properly done commits is trivial,
merging those 2 list is also trivial.

The conversion of a commit message to a release notes message is not
so trivial, but also not massivly complex, but is a single threaded
(one person usually does all that work, Glen or the lead RE for that
release.)  Having this work shareable would be a huge win.

And like UPDATING a minimal set of self documentation in the top
of the file would probably go further than anything off in the
developers handbook.

Oh, and it is also possible to use this to do a:
r456789: Relnotes: NO, commit message is incorrect
                r456789 was reverted in r456987

to record the fact that there is no need to mention that specific
commit in the release notes, it was erroniously marked, or become
irrelevant for some reason, aka revert, etc...

> Warner
--
Rod Grimes                                                 [hidden email]
_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-hackers
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: release notes file

Cy Schubert-4
In reply to this post by Mark Johnston-2
On June 23, 2019 12:18:18 PM PDT, Mark Johnston <[hidden email]> wrote:

>Hi,
>
>Today we add a Relnotes tag to commits that warrant a release note.
>My impression is that it doesn't work so well: if a committer forgets
>or doesn't know to add one there's no way to amend the commit message
>(same for MFCs), and a commit message isn't a convenient place to write
>the text of a release note.  I would like to propose adding a top-level
>RELNOTES file instead, which like UPDATING would document notes for
>specific commits.  It would be truncated every time the head branch is
>forked, and changes to it would be MFCed.  This fixes the
>above-mentioned problems and would hopefully reduce the amount of time
>needed by re@ to compile release notes.
>
>For example:
>
>Index: RELNOTES
>===================================================================
>--- RELNOTES (nonexistent)
>+++ RELNOTES (working copy)
>@@ -0,0 +1,8 @@
>+Release notes for FreeBSD 13.0.
>+
>+r349286:
>+ swapon(8) can now erase a swap device immediately before
>+ enabling it, similar to newfs(8)'s -E option.  This behaviour
>+ can be specified by adding -E to swapon(8)'s command-line
>+ parameters, or by adding the "trimonce" option to a swap
>+ device's /etc/fstab entry.
>
>What do folks think?
>_______________________________________________
>[hidden email] mailing list
>https://lists.freebsd.org/mailman/listinfo/freebsd-hackers
>To unsubscribe, send any mail to
>"[hidden email]"

There should also be a Makefile target to install it into /etc for people who do not install sources.


--
Pardon the typos and autocorrect, small keyboard in use.
Cheers,
Cy Schubert <[hidden email]>
FreeBSD UNIX: <[hidden email]> Web: http://www.FreeBSD.org

        The need of the many outweighs the greed of the few.
_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-hackers
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: release notes file

Cy Schubert-4
In reply to this post by Oliver Pinter-4
On June 23, 2019 2:20:13 PM PDT, Oliver Pinter <[hidden email]> wrote:

>On Sunday, June 23, 2019, Mark Johnston <[hidden email]> wrote:
>
>> Hi,
>>
>> Today we add a Relnotes tag to commits that warrant a release note.
>> My impression is that it doesn't work so well: if a committer forgets
>> or doesn't know to add one there's no way to amend the commit message
>> (same for MFCs), and a commit message isn't a convenient place to
>write
>> the text of a release note.  I would like to propose adding a
>top-level
>> RELNOTES file instead, which like UPDATING would document notes for
>> specific commits.  It would be truncated every time the head branch
>is
>> forked, and changes to it would be MFCed.  This fixes the
>> above-mentioned problems and would hopefully reduce the amount of
>time
>> needed by re@ to compile release notes.
>
>
>
>In the future with git you could easily add meta infos for specific
>commits. The project currently using this to store git-svn meta, but
>you
>can add more the one note to each commit.
>W
>
>
>
>
>>
>> For example:
>>
>> Index: RELNOTES
>> ===================================================================
>> --- RELNOTES    (nonexistent)
>> +++ RELNOTES    (working copy)
>> @@ -0,0 +1,8 @@
>> +Release notes for FreeBSD 13.0.
>> +
>> +r349286:
>> +       swapon(8) can now erase a swap device immediately before
>> +       enabling it, similar to newfs(8)'s -E option.  This behaviour
>> +       can be specified by adding -E to swapon(8)'s command-line
>> +       parameters, or by adding the "trimonce" option to a swap
>> +       device's /etc/fstab entry.
>>
>> What do folks think?
>> _______________________________________________
>> [hidden email] mailing list
>> https://lists.freebsd.org/mailman/listinfo/freebsd-hackers
>> To unsubscribe, send any mail to
>"[hidden email]"
>>
>_______________________________________________
>[hidden email] mailing list
>https://lists.freebsd.org/mailman/listinfo/freebsd-hackers
>To unsubscribe, send any mail to
>"[hidden email]"

It should be a .md file to format it properly on github. The more I think of it, a Makefile target to install it to / instead of /etc is more intuitive.


--
Pardon the typos and autocorrect, small keyboard in use.
Cheers,
Cy Schubert <[hidden email]>
FreeBSD UNIX: <[hidden email]> Web: http://www.FreeBSD.org

        The need of the many outweighs the greed of the few.
_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-hackers
To unsubscribe, send any mail to "[hidden email]"
12