FW: [Bug 744918] Update Help Manual for Mike Alexanders mods to Advanced Portfolio Rpt

[Geert Janssens]

On Saturday 21 March 2015 11:41:12 Chris Good wrote:
> Hi Geert,
> 
> 
> 
> Thanks very much for actioning my patch.
> 
You're most welcome. I'm quite happy you are working on the documentation.
> 
> 
> I’ll update the wiki Documentation_Update_Instructions to add a note
> saying bug version should be git-maint if patch should be included in
> the next stable release.
> 
This is correct but confusing. And I am guilty of adding to this confusion :(

Both the work on git-maint and the work on git-master eventually end up in a "stable" release. 
The difference is that patches on git-maint will end up in the next release of the current stable 
series (at this time 2.6.x), while patches on git-master will only appear in the next stable series 
(which will be 2.8.x).

Unfortunately the developers use different names to refer to these releases depending on the 
context.

I tend to use "major release" to refer to the first release in the next stable series (2.8.0) and 
"stable release" to refer to a release in the current stable series (2.6.x). Since we only support 
one stable series at the time there is usually no overlap in this naming.

But technically this is incorrect. More correct would be to name releases based on which part of 
the version number changes. For example:
2.x.x -> 3.0.0 = major release (major version number changed)
2.6.x -> 2.8.0 = minor release (minor version number changed)
2.6.5 -> 2.6.6 = micro release (micro version number changed)

The last one is also referred to as "bugfix release" and I believe even "point release".

I personally keep having trouble calling a change from 2.6.x to 2.8.0 a "minor release" even if it 
is indeed the minor version number that changes. In the gnucash release cycle there are 
usually big changes between stable series which in my mind add up to a major update, so a 
major release. Also a change in major version number is rather arbitrary in gnucash. We don't 
have hard rules for that as we do for a change in minor version number.

> 
> 
> Is it also correct to add: bug version should be git-master if the
> documentation patch applies to the next unstable release?
> 
Technically that is correct.

However the unstable releases are not the focus of development. They are only pre-releases 
intended for testing. They all eventually lead up to a "major/minor release" in the next stable 
series. And that release is the relevant one, not the unstable releases.

So I think you can mention unstable releases, yet explain that git-master will lead up to the 
next "major/minor release" or stable release series.

You'll note that I keep adding "major" as I really have issues with calling these big updates 
"minor". Perhaps we can have a brainstorm over this among developers and interested 
commmunity members.

> 
> 
> Shall I also add to http://wiki.gnucash.org/wiki/Release_Schedule
> something like:
> 
> 
> 
> Stable releases have an odd version number. E.g. 2.4, 2.6, 2.8…
> 
> Unstable releases have an even version number E.g. 2.5, 2.7, 2.9… and
> are only intended for developers working on longer term
> modifications.
> 
Ehm, 2.4 and 2.6,... are *even* minor version numbers, while 2.5, 2.7,... are *odd* as far as my 
knowledge of English goes...

And it's not quite so that unstable releases are intended for developers only. Quite on the 
contrary. Unstable releases are intended for testers (which can be developers, but are usually 
interested community members that don't have the time/skills to build gnucash from scratch). 
They are meant to expose the developers' work to a wider audience so the can test and report 
bugs against the major changes developers have been working on. These come late in a major 
development cycle and are intended to stabilize the work so far for the next big release. So by 
the time unstable releases are issued, relevant longer term modifications should be nearly done 
(except for some bugfixing).
> 
> 
> This isn’t actually stated anywhere that I have found.
> 
Feel free to explain unstable releases and their numbering scheme. I would suggest though to 
keep it as a side note though instead of using it to explain the difference between git-maint and 
git-master in bugzilla. That would lead to confusion IMHO.

Geert