Announcement / Documentation question

[atom]

I have a wish and a question.

Announcements: Would it be possible to mention in the "Full patch notes" also the github number, so that it is easier to find the changes ?

Will there be a separate documentation for 21.1 or has so little changed that the old one still applies ?

[lfirewall1243]

I have a wish and a question.

Announcements: Would it be possible to mention in the "Full patch notes" also the github number, so that it is easier to find the changes ?

Will there be a separate documentation for 21.1 or has so little changed that the old one still applies ?

The numberes are shown in the changelogs

Most things are the same
And if big things are new the existing documentations will be edited

[franco]

Hi,

For readability and clarity we will not release announcements with "git log --oneline" dumps or similar. The release engineering not always a straight path between versions. If you need to follow git please use the respective stable branches and tagging... I always use something like this:

# cd core.git
# git checkout stable/21.1
# git log --stat -p --reverse ...21.1

It shows all the changes after tag 21.1 in chronological order., so that means all the things that land in 21.1.1.

We did discuss the possibility to add stable branches to the documentation so that each version has their own manual, but the amount of duplication is too high and there are not so many moving parts from version to version that the extra work is necessary.


Cheers,
Franco

[atom]

Hi Franco,

thanks a lot for your explanation.

I would like to show my problem with the following example:
The fully patch notes agains 20.7.8 contains the line

Code: [Select]

ipsec: NAT with multiple phase 2 (sponsored by m.a.x. it)

It would be great to have a link at the end of this line to github (https://github.com/opnsense/core/issues/4460) in this case, so that I can jump directly to the issue.

Then I'll like to know from a Addendum for 21.1: Is there something I must change after the upgrade to 21.1 to fix the phase2 issue or not.

Regards,
atom

[franco]

Hi atom,

I understand your concern, but to my knowledge the patch extended behaviour (automatic migration) so it did not require extra steps on the user's side.

I'm happy to point to commits or issues as time permits here. In this particular case the issue is a good thing to reference, but there were a number of commits and there was no backport since it never went to 20.7.x which makes it harder to trace code-wise (WRT your initial question). Unless I misunderstood "github number" meaning issue number instead of git commit. That makes more sense now...


Cheers,
Franco

[franco]

PS: added two links to relevant features https://github.com/opnsense/changelog/commit/a61f2055a4b

[atom]

Hi Franco,

great.

Thank you very much,
atom

[Ricardo]

PS: added two links to relevant features https://github.com/opnsense/changelog/commit/a61f2055a4b

Hi Franco, its me again

I tried to figure out such update that you described above, becomes visible where?

a) In this forum, under Announcements\release 21.1, you would need to publish a new post with the above change manually, otherwise it will never get there, right?
b) The opnsense GUI itself will not show this change under Firmware\Changelog either, right? I dont really see what is the source of those changelogs (offline static local files saved to the filesystem of thr opnsense server, or url to retrieve the online version at the time of checking that changelog, so always retrieves the latest most uptodate content?). If that is offline static file, it will not be updated with your new additions, right?
c) I went to: https://docs.opnsense.org/releases.html
It does not even list 21.1 as a released branch, so that is outdated for the moment I am sure.
d) I discovered a 4th place today:
https://docs.opnsense.org/manual/how-tos/changelog.html

this mentions github as the 4th source:
https://github.com/opnsense/changelog/tree/master/doc

-> but this link seems broken (404)

e) Reading the 21.1 notes when unlocking it, spotted this line in the text:

"Make sure to read the migration notes and adjust for possible minor breaking changes."

Would be helpful if that warning would link to a url where I can find the 21.1-specific migration/upgrade notes. As currently I am unaware if any such notes do exist, and where?

-> d)  was the main point of my post
But if you can respond on a), b), c) and e) that would clear up some confusion.

[AdSchellevis]

@Ricardo We're currently in the process of moving some things around, which is why some of the links got broken last week. Usually we try to publish the docs close to the release (this time we're lagging behind a bit), the new location for the source of all these logs is https://github.com/opnsense/changelog/tree/master/community

Changelogs for the product itself are shipped to the mirror and downloaded as a single txz (changelog.txz) file when being asked by the gui.

If there are migration notes, they would normally be mentioned in the changelog, when following all upgrades you only have to read one, when migrating from an older version, there's more reading todo. An example of such a note would be the removal of mpd5 plugins in 20.7 for example (https://github.com/opnsense/changelog/blob/1663700184747c800c64f5e009bcf857718fc292/community/20.7/20.7#L41)

I guess this should answer most of your questions

Best regards,

Ad

[franco]

Hmm, I added these only yesterday on a Saturday. I would expect an update of the GUI changelogs by Monday.

There's no moving parts in 20.7 vs. 21.1 so there are no migration notes as Ad said.


Cheers,
Franco