NuttX releases and release notes

[Matteo Golin <ma...@gmail.com>]

Hello everyone,

While making changes to some of the documentation here on NuttX, I noticed that some of the very old NuttX releases
actually had release notes included.

I took a look at the NuttX GitHub page, and now it seems that version updates (for instance, 12.9.0 recently) are
created as "tags" on GitHub (listed here https://github.com/apache/nuttx/tags), as opposed to "releases" (here there are
none https://github.com/apache/nuttx/releases).

Some of the other open source projects I follow make use of the release feature on GitHub, which actually makes the
release visible on GitHub's explore page and also has additions like a "latest" tag, etc. Here's one by FreeCAD: https://github.com/FreeCAD/FreeCAD/releases/tag/1.0.1

Another great thing to add would be to bring back release notes. I am fairly certain this can be automated using CI
tools, which track which issues were closed and can also add notes based on the commit messages (i.e. sort by the topic
that is enforced in front of each commit message). This was one of the first ones I found: https://github.com/marketplace/actions/release-notes-generator

I think bringing back the release notes might help NuttX users see the progress being made towards NuttX become more
stable (and also supporting many more features). They'll be able to see all the bugs that contributors fix with each
release and also see all the new features highlighted. This is much nicer than having to check on issues on the GitHub
page, and it might also help users to discover some new capabilities that NuttX has.

One final idea: some of the releases that projects on GitHub make are nightly releases (such as this one by FreeCAD
https://github.com/FreeCAD/FreeCAD/releases/tag/weekly-2025.05.19), and they're marked as "pre-releases". Those releases
have different content in their descriptions, like the process to build and launch the application. I think NuttX could
leverage this for the RC releases during voting periods by having pre-releases that automatically include all of the
instructions for testing the release candidate and issuing a vote for or against it. This might help involve more users
in RC testing, even if they weren't originally part of the mailing list. Of course they will still have to vote on the
mailing list, but this is another location where they can be exposed to the RC and read about the testing procedure
instead of having to find it themselves in the docs.

Is there any interest in setting up some of these release options on our GitHub? I can maybe look into it further,
starting with generating release notes automatically from commit history.

-- 
Matteo Golin

Re: NuttX releases and release notes

[Matteo Golin <ma...@gmail.com>]

On Wed, May 21, 2025 at 10:59:08AM +0200, Alin Jerpelea wrote:
> Hi Mateo,
> 
> I like the initiative but there are some things to consider

The replies to my email make a lot of sense. There are definitely some things I didn't know about! I put my responses
below:

> 
> On Tue, May 20, 2025 at 11:47 PM Tomek CEDRO <to...@cedro.info> wrote:
> 
> > Hey there Matteo :-)
> >
> > On Tue, May 20, 2025 at 10:24 PM Matteo Golin <ma...@gmail.com>
> > wrote:
> > > Hello everyone,
> > > While making changes to some of the documentation here on NuttX, I
> > noticed that some of the very old NuttX releases
> > > actually had release notes included.
> >
> > +1 for release notes beyond list of included commits, especially
> > breaking changes should have separate section with description and
> > workaround for each one :-)
> >
> 
> +1 release notes improvements are always welcomed.Please check the script
> that generates them (in tools folder).

Great, I didn't know we had that! Extending this is a better solution then a CI action so I will take a look at this.

> 
> >
> >
> > > I took a look at the NuttX GitHub page, and now it seems that version
> > updates (for instance, 12.9.0 recently) are
> > > created as "tags" on GitHub (listed here
> > https://github.com/apache/nuttx/tags), as opposed to "releases" (here
> > there are
> > > none https://github.com/apache/nuttx/releases).
> >
> > +1 for branch for each release +1 for releases with github releases
> > (its done automatically when branch/tag is provided). That would put
> > some better insight on project pace / development for newcomers and
> > could attract new people :-)
> >
> > The question is if this is a big complication for Alin and if help
> > here is needed? :-)
> >
> >
> -1 our releases are signed and hosted on Apache servers.
> I don't think that it is a god idea to have separate releases on github.
> For each release we have the stabilization branch ex releases/12.9.0 which
> contains all the code included in a release.
> This branch can be used for generating release notes and will be updated
> with security code for a security release
> 

> 
> >
> > > Some of the other open source projects I follow make use of the release
> > feature on GitHub, which actually makes the
> > > release visible on GitHub's explore page and also has additions like a
> > "latest" tag, etc. Here's one by FreeCAD:
> > https://github.com/FreeCAD/FreeCAD/releases/tag/1.0.1
> >
> > as above this can be generated automatically based on github release
> > workflow :-)
> >
> 
> -1 our releases are signed and hosted on Apache servers
> 

This makes sense, I don't want to add a second separate release. However, the "releases" page on GitHub is functionally
very similar to the "tags" page that we are already using. I have seen quite a few different projects that publish these
secure signed releases (Neovim I believe has SHA codes included: https://github.com/neovim/neovim/releases/tag/nightly).
However, I do understand this creates more work. Like Tomek mentioned, a big reason to use GitHub releases is that it
gets pushed out to the GitHub explore page and attracts new users. Would it be possible maybe to have a release CI grab
the signed releases from the Apache servers and add them as the release artifacts on GitHub? Or even to just link to the
Apache server where the release is hosted (without posting artifacts)? This would be almost the same as the current
method of using tags (I think), just visible on GitHub explore. We can also grab the release notes from the NuttX
release docs (https://nuttx.apache.org/releases/12.9.0/) or re-running the same tools script to put in the release
description there. I don't want to generate more work for you so all the fetching would be automated to create the
release on GitHub, with as little effort as making the tag. What do you think?

> 
> >
> > > Another great thing to add would be to bring back release notes. I am
> > fairly certain this can be automated using CI
> > > tools, which track which issues were closed and can also add notes based
> > on the commit messages (i.e. sort by the topic
> > > that is enforced in front of each commit message). This was one of the
> > first ones I found:
> > https://github.com/marketplace/actions/release-notes-generator
> > >
> > > I think bringing back the release notes might help NuttX users see the
> > progress being made towards NuttX become more
> > > stable (and also supporting many more features). They'll be able to see
> > all the bugs that contributors fix with each
> > > release and also see all the new features highlighted. This is much
> > nicer than having to check on issues on the GitHub
> > > page, and it might also help users to discover some new capabilities
> > that NuttX has.
> >
> > +++1 :-)
> >
> >
> 0 for each release we have release notes in confluence and as a separate
> file in each release. maybe it is better to improve the release data
> instead of adding a new source

I suppose I missed the release notes files for our later releases, but I am now aware of the script we have for
generating release notes that you mentioned! I'll just take a look at that script and see if there are any changes I can
propose to improve the notes.

> 
> 
> >
> >
> > > One final idea: some of the releases that projects on GitHub make are
> > nightly releases (such as this one by FreeCAD
> > > https://github.com/FreeCAD/FreeCAD/releases/tag/weekly-2025.05.19), and
> > they're marked as "pre-releases". Those releases
> > > have different content in their descriptions, like the process to build
> > and launch the application. I think NuttX could
> > > leverage this for the RC releases during voting periods by having
> > pre-releases that automatically include all of the
> > > instructions for testing the release candidate and issuing a vote for or
> > against it. This might help involve more users
> > > in RC testing, even if they weren't originally part of the mailing list.
> > Of course they will still have to vote on the
> > > mailing list, but this is another location where they can be exposed to
> > the RC and read about the testing procedure
> > > instead of having to find it themselves in the docs.
> >
> > Alin creates RC branches for testing. Also master can be used for most
> > up to date code. There is URL on github that can download current /
> > selected branch / tag as zip / tar.gz package. So not sure here. It is
> > easier to just use git rather than "daily builds". NuttX is so
> > customizable and portable that it is not really possible to create any
> > kind of "generic build" :-)
> >
> >
> -1 we follow a quarterly release process. 1 month before the release the
> master is branched out and the new release branch will be tested and
> receive only fixes.
> after 30 days the first release candidate is created, signed and sent for
> community testing and vote. if issues are found the new patches are ported
> to the release branch
> and a new release candidate is created, signed and submitted for community
> vote.(the process repeats until we have a release)
> Our project does not work with feature branches and the described model
> would not fit our release model and available resources.

Sorry, to clarify I was not suggesting that NuttX have "daily builds". Moreso that when a release candidate branch is
created, a GitHub "pre-release" is created with that branch for people to download and test. Although I understand now
that testing and creating fixes for the release candidate branch is part of this process, and it would just be better
for RC testers to always pull from the RC branch so that they have the latest fixes during the test period. I agree that
this doesn't fit with the NuttX workflow very well. I will try to think if there is any way to get more eyes on our RCs
so that there is potentially more testers.

> 
> > > Is there any interest in setting up some of these release options on our
> > GitHub? I can maybe look into it further,
> > > starting with generating release notes automatically from commit history.
> >
> > I think something like this is already here
> > https://nuttx.apache.org/releases/ but releases on github seems more
> > obvious :-)
> >
> >
> > Thanks Matteo! :-)
> > Tomek
> >
> > --
> > CeDeROM, SQ7MHZ, http://www.tomek.cedro.info
> 
> 
>  Thanks Matteo! :-)
> Alin

-- 
Matteo Golin

Re: NuttX releases and release notes

[Tomek CEDRO <to...@cedro.info>]

On Wed, May 21, 2025 at 10:59 AM Alin Jerpelea <je...@gmail.com> wrote:
> Hi Mateo,
> I like the initiative but there are some things to consider
>
> On Tue, May 20, 2025 at 11:47 PM Tomek CEDRO <to...@cedro.info> wrote:
> > On Tue, May 20, 2025 at 10:24 PM Matteo Golin <ma...@gmail.com>
> > wrote:
> > > I took a look at the NuttX GitHub page, and now it seems that version
> > updates (for instance, 12.9.0 recently) are
> > > created as "tags" on GitHub (listed here
> > https://github.com/apache/nuttx/tags), as opposed to "releases" (here
> > there are
> > > none https://github.com/apache/nuttx/releases).
> >
> > +1 for branch for each release +1 for releases with github releases
> > (its done automatically when branch/tag is provided). That would put
> > some better insight on project pace / development for newcomers and
> > could attract new people :-)
> >
> > The question is if this is a big complication for Alin and if help
> > here is needed? :-)
> >
> >
> -1 our releases are signed and hosted on Apache servers.
> I don't think that it is a god idea to have separate releases on github.
> For each release we have the stabilization branch ex releases/12.9.0 which
> contains all the code included in a release.
> This branch can be used for generating release notes and will be updated
> with security code for a security release

Hmm to be honest I also usually use GitHub releases for most
projects.. and we can put signed artifacts from Apache servers on
GitHub manually for NuttX releases even if the auto-release-automation
is not used? I see that as project visibility increase too :-)


-- 
CeDeROM, SQ7MHZ, http://www.tomek.cedro.info

Re: NuttX releases and release notes

[Alin Jerpelea <je...@gmail.com>]

Hi Mateo,

I like the initiative but there are some things to consider

On Tue, May 20, 2025 at 11:47 PM Tomek CEDRO <to...@cedro.info> wrote:

> Hey there Matteo :-)
>
> On Tue, May 20, 2025 at 10:24 PM Matteo Golin <ma...@gmail.com>
> wrote:
> > Hello everyone,
> > While making changes to some of the documentation here on NuttX, I
> noticed that some of the very old NuttX releases
> > actually had release notes included.
>
> +1 for release notes beyond list of included commits, especially
> breaking changes should have separate section with description and
> workaround for each one :-)
>

+1 release notes improvements are always welcomed.Please check the script
that generates them (in tools folder).

>
>
> > I took a look at the NuttX GitHub page, and now it seems that version
> updates (for instance, 12.9.0 recently) are
> > created as "tags" on GitHub (listed here
> https://github.com/apache/nuttx/tags), as opposed to "releases" (here
> there are
> > none https://github.com/apache/nuttx/releases).
>
> +1 for branch for each release +1 for releases with github releases
> (its done automatically when branch/tag is provided). That would put
> some better insight on project pace / development for newcomers and
> could attract new people :-)
>
> The question is if this is a big complication for Alin and if help
> here is needed? :-)
>
>
-1 our releases are signed and hosted on Apache servers.
I don't think that it is a god idea to have separate releases on github.
For each release we have the stabilization branch ex releases/12.9.0 which
contains all the code included in a release.
This branch can be used for generating release notes and will be updated
with security code for a security release


>
> > Some of the other open source projects I follow make use of the release
> feature on GitHub, which actually makes the
> > release visible on GitHub's explore page and also has additions like a
> "latest" tag, etc. Here's one by FreeCAD:
> https://github.com/FreeCAD/FreeCAD/releases/tag/1.0.1
>
> as above this can be generated automatically based on github release
> workflow :-)
>

-1 our releases are signed and hosted on Apache servers


>
> > Another great thing to add would be to bring back release notes. I am
> fairly certain this can be automated using CI
> > tools, which track which issues were closed and can also add notes based
> on the commit messages (i.e. sort by the topic
> > that is enforced in front of each commit message). This was one of the
> first ones I found:
> https://github.com/marketplace/actions/release-notes-generator
> >
> > I think bringing back the release notes might help NuttX users see the
> progress being made towards NuttX become more
> > stable (and also supporting many more features). They'll be able to see
> all the bugs that contributors fix with each
> > release and also see all the new features highlighted. This is much
> nicer than having to check on issues on the GitHub
> > page, and it might also help users to discover some new capabilities
> that NuttX has.
>
> +++1 :-)
>
>
0 for each release we have release notes in confluence and as a separate
file in each release. maybe it is better to improve the release data
instead of adding a new source


>
>
> > One final idea: some of the releases that projects on GitHub make are
> nightly releases (such as this one by FreeCAD
> > https://github.com/FreeCAD/FreeCAD/releases/tag/weekly-2025.05.19), and
> they're marked as "pre-releases". Those releases
> > have different content in their descriptions, like the process to build
> and launch the application. I think NuttX could
> > leverage this for the RC releases during voting periods by having
> pre-releases that automatically include all of the
> > instructions for testing the release candidate and issuing a vote for or
> against it. This might help involve more users
> > in RC testing, even if they weren't originally part of the mailing list.
> Of course they will still have to vote on the
> > mailing list, but this is another location where they can be exposed to
> the RC and read about the testing procedure
> > instead of having to find it themselves in the docs.
>
> Alin creates RC branches for testing. Also master can be used for most
> up to date code. There is URL on github that can download current /
> selected branch / tag as zip / tar.gz package. So not sure here. It is
> easier to just use git rather than "daily builds". NuttX is so
> customizable and portable that it is not really possible to create any
> kind of "generic build" :-)
>
>
-1 we follow a quarterly release process. 1 month before the release the
master is branched out and the new release branch will be tested and
receive only fixes.
after 30 days the first release candidate is created, signed and sent for
community testing and vote. if issues are found the new patches are ported
to the release branch
and a new release candidate is created, signed and submitted for community
vote.(the process repeats until we have a release)
Our project does not work with feature branches and the described model
would not fit our release model and available resources.


> > Is there any interest in setting up some of these release options on our
> GitHub? I can maybe look into it further,
> > starting with generating release notes automatically from commit history.
>
> I think something like this is already here
> https://nuttx.apache.org/releases/ but releases on github seems more
> obvious :-)
>
>
> Thanks Matteo! :-)
> Tomek
>
> --
> CeDeROM, SQ7MHZ, http://www.tomek.cedro.info


 Thanks Matteo! :-)
Alin

Re: NuttX releases and release notes

[Tomek CEDRO <to...@cedro.info>]

Hey there Matteo :-)

On Tue, May 20, 2025 at 10:24 PM Matteo Golin <ma...@gmail.com> wrote:
> Hello everyone,
> While making changes to some of the documentation here on NuttX, I noticed that some of the very old NuttX releases
> actually had release notes included.

+1 for release notes beyond list of included commits, especially
breaking changes should have separate section with description and
workaround for each one :-)


> I took a look at the NuttX GitHub page, and now it seems that version updates (for instance, 12.9.0 recently) are
> created as "tags" on GitHub (listed here https://github.com/apache/nuttx/tags), as opposed to "releases" (here there are
> none https://github.com/apache/nuttx/releases).

+1 for branch for each release +1 for releases with github releases
(its done automatically when branch/tag is provided). That would put
some better insight on project pace / development for newcomers and
could attract new people :-)

The question is if this is a big complication for Alin and if help
here is needed? :-)


> Some of the other open source projects I follow make use of the release feature on GitHub, which actually makes the
> release visible on GitHub's explore page and also has additions like a "latest" tag, etc. Here's one by FreeCAD: https://github.com/FreeCAD/FreeCAD/releases/tag/1.0.1

as above this can be generated automatically based on github release
workflow :-)


> Another great thing to add would be to bring back release notes. I am fairly certain this can be automated using CI
> tools, which track which issues were closed and can also add notes based on the commit messages (i.e. sort by the topic
> that is enforced in front of each commit message). This was one of the first ones I found: https://github.com/marketplace/actions/release-notes-generator
>
> I think bringing back the release notes might help NuttX users see the progress being made towards NuttX become more
> stable (and also supporting many more features). They'll be able to see all the bugs that contributors fix with each
> release and also see all the new features highlighted. This is much nicer than having to check on issues on the GitHub
> page, and it might also help users to discover some new capabilities that NuttX has.

+++1 :-)



> One final idea: some of the releases that projects on GitHub make are nightly releases (such as this one by FreeCAD
> https://github.com/FreeCAD/FreeCAD/releases/tag/weekly-2025.05.19), and they're marked as "pre-releases". Those releases
> have different content in their descriptions, like the process to build and launch the application. I think NuttX could
> leverage this for the RC releases during voting periods by having pre-releases that automatically include all of the
> instructions for testing the release candidate and issuing a vote for or against it. This might help involve more users
> in RC testing, even if they weren't originally part of the mailing list. Of course they will still have to vote on the
> mailing list, but this is another location where they can be exposed to the RC and read about the testing procedure
> instead of having to find it themselves in the docs.

Alin creates RC branches for testing. Also master can be used for most
up to date code. There is URL on github that can download current /
selected branch / tag as zip / tar.gz package. So not sure here. It is
easier to just use git rather than "daily builds". NuttX is so
customizable and portable that it is not really possible to create any
kind of "generic build" :-)


> Is there any interest in setting up some of these release options on our GitHub? I can maybe look into it further,
> starting with generating release notes automatically from commit history.

I think something like this is already here
https://nuttx.apache.org/releases/ but releases on github seems more
obvious :-)


Thanks Matteo! :-)
Tomek

-- 
CeDeROM, SQ7MHZ, http://www.tomek.cedro.info