Re: Beyond 2.8 - some design thoughts

[Frank H. Ellenberger]

Am 03.01.2018 um 17:41 schrieb Derek Atkins:
> I see no reason that we can't jump from 2.7.x to 3.0[.0] when we release.
> And since we DID upgrade to GTK3, I think we should do that.

+1

> As for whether to drop the third entry is less important to me, but I
> still think it makes sense to have 3.0.0, 3.0.1, etc., for bugfixes and
> leave 3.1/3.2 for more major changes.

+1

Maintainers might have a policy to update bugfixes in their current
release, mayor changes in the next release and for fundamental changes
both versions.

The 3 levels also should give admins and users a clue how much time is
needed for
 dependency changes and
 understanding new concepts.

> I'm fine with dropping the even/odd and just jumping t0 3.0.80 (or 90)
> for testing pre-releases.

The rule is simple: Do not install the odd version on productive systems!

~Frank
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Beyond 2.8 - some design thoughts

[Derek Atkins]

John Ralls  writes:

>> 2. Versioning.
>> 
>> We currently use a version scheme gigantic.major.minor[-build]. Like 2.6.19 
>> (and an optional -2 if we had to release more than once to get it right). 
>> For 
>> the 3 levels we really only use two. The 2 in front has been updated when 
>> gnucash migrated from gtk to gtk2.  We will migrate to gtk3 for gnucash 2.8 
>> yet we don't changed to 3.0 as a result. The migration to gtk2 has
>> been a long
>> time ago and the software world has evolved since then. Release cycles in 
>> general have shortened. Incremental changes are usually preferred over big 
>> bang changes. So I think our numbering scheme is in for a modernization.
>> 
>> Here's my proposal:
>> After the 2.8 lifecycle let's drop one number and stick with major.minor[-
>> build] instead. 
>> Major releases would increment the first number. Bugfix releases the second.
>> 
>> So after 2.8 the next major release would be 3.0, bugfix releases for that 
>> major release would become 3.1, 3.2, 3.4...
>> 
>> I would drop the idea of odd numbers being development snapshots and even 
>> numbers being stable ones. Instead I see several options, I haven't decided 
>> which one is most elegant/kludgy:
>> 
>> Option A: let's number development snapshots starting from
>> x.90. That gives us
>> 10 development snapshots. If that's not enough we can either choose
>> to start a
>> bit earlier, like x.80 or from x.98 jump to x.980 to give us 20 more.
>> Option B: as a variation all development snapshots do use a 3 number 
>> version: 
>> x.99.z with 99 clearly indicating "right before the next major release" and 
>> z 
>> incrementing with each snapshot.
>> 
>> This makes development snapshots slightly more verbose in their numbering 
>> but 
>> gives us cleanly incrementing stable releases. The latter are more visible 
>> to 
>> most users, so I personally care more about those.
>> 
>> The development snapshots between 2.8 and 3.0 fall a bit in between. We 
>> could 
>> choose to handle them old style or new style as we see fit. Old style would 
>> mean we'd still work with a 2.9.x series. New style would mean we'd
>> start with
>> 2.8.90/2.8.99.1 as we see fit.
>> 
>> Thoughts ?
>
> I’m indifferent to the versioning system as long as it’s consistent,
> but the distro packagers aren’t. Some of them recite the “Semantic
> Versioning” [1] mantra even though it really applies only to
> libraries.
>
> Back when we released 2.6 we were unsure about whether the coming
> version would be 2.8 or 3.0. One of the criteria proposed was that we
> should call it 3.0 if we upgraded to Gtk+3. Well, we have, so maybe
> the coming release should be 3.0.0 instead of 2.8.0. That would
> certainly be consistent with the Gnome guidelines [2] that include a
> major change in the GUI as a reason for bumping the major version.
>
> Should some of the component libraries (especially libgnucash) have
> separate versioning that follows the semantic versioning rules?

I see no reason that we can't jump from 2.7.x to 3.0[.0] when we release.
And since we DID upgrade to GTK3, I think we should do that.

As for whether to drop the third entry is less important to me, but I
still think it makes sense to have 3.0.0, 3.0.1, etc., for bugfixes and
leave 3.1/3.2 for more major changes.

I'm fine with dropping the even/odd and just jumping t0 3.0.80 (or 90)
for testing pre-releases.

> Regards,
> John Ralls

-derek

-- 
   Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
   Member, MIT Student Information Processing Board  (SIPB)
   URL: http://web.mit.edu/warlord/PP-ASEL-IA N1NWH
   warl...@mit.eduPGP key available
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Beyond 2.8 - some design thoughts

[Geert Janssens]

Op vrijdag 29 december 2017 18:23:57 CET schreef John Ralls:
> > On Dec 29, 2017, at 8:20 AM, Geert Janssens 
> > wrote:> 
> > Op vrijdag 29 december 2017 10:11:08 CET schreef Alen Siljak:
> >> I'd like to add that, to me, the difference between stable and unstable
> >> version is obvious enough if I see v2.8.0-alpha1, 2.8.0-alpha2,
> >> 2.8.0-beta1, 2.8.0-rc1, and then 2.8.0. I see no need for separate
> >> version
> >> numbers.
> > 
> > That's a good point. I should check though whether our build system can
> > handle this. If it does or if we can make it so, using explicit
> > alpha/beta/rc strings would be very clear. It would be also require some
> > getting used to as until now we never made an explicit distinction
> > between alpha/beta/rc (though we imply it sometimes in warnings). Should
> > we ? And if so, what would be the criterion ?
> 
> I don’t think that the distros would like that scheme. They want suffixes
> separated by a hyphen to be reserved for their own nefarious purposes
> (mostly designating releases with back ported patches from the project’s
> VCS).
> 
> Better, I think, to use x.9y or perhaps x.9yy for unstable releases.
> 
> Regards,
> John Ralls

Fair point too. Keeps our changes to the build system smaller as well.

I believe 10 unstable releases may be a tad sharp (we had 11 for the 2.5 
series). So let's go for the x.9yy scheme instead.

To summarize:

1. our new version scheme will have two numbers x.y

2. The x number will increase for releases with backwards incompatible changes 
(which we typically call major releases)

3. The y number increases for releases with bugfixes or backwards compatible 
improvements (which we typically call bugfix releases)

4. Whenever the x number increases, the y number is reset to 0

5. Major releases are usually preceded by a number of unstable releases to 
allow wider testing and give translators time to translate new and changed 
strings in the upcoming major release. These unstable releases will be 
numbered x.9zz (so the second number can range from 900 to 999).

I believe that is what most have roughly agreed to (or at least have no strong 
objections against).

John also suggested we can skip 2.8.0 and go straight for 3.0. I'm liking that 
idea more and more. It's indeed consistent with the gnome guidelines and 
allows us to start using the new scheme already now.

Any more closing comments before we officially adopt this new scheme ?

Regards,

Geert
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Beyond 2.8 - some design thoughts

[John Ralls]

> On Dec 29, 2017, at 8:20 AM, Geert Janssens  
> wrote:
> 
> Op vrijdag 29 december 2017 10:11:08 CET schreef Alen Siljak:
>> I'd like to add that, to me, the difference between stable and unstable
>> version is obvious enough if I see v2.8.0-alpha1, 2.8.0-alpha2,
>> 2.8.0-beta1, 2.8.0-rc1, and then 2.8.0. I see no need for separate version
>> numbers.
> 
> That's a good point. I should check though whether our build system can 
> handle 
> this. If it does or if we can make it so, using explicit alpha/beta/rc 
> strings 
> would be very clear. It would be also require some getting used to as until 
> now we never made an explicit distinction between alpha/beta/rc (though we 
> imply it sometimes in warnings). Should we ? And if so, what would be the 
> criterion ?

I don’t think that the distros would like that scheme. They want suffixes 
separated by a hyphen to be reserved for their own nefarious purposes (mostly 
designating releases with back ported patches from the project’s VCS).

Better, I think, to use x.9y or perhaps x.9yy for unstable releases.

Regards,
John Ralls

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Beyond 2.8 - some design thoughts

[Geert Janssens]

Op vrijdag 29 december 2017 10:11:08 CET schreef Alen Siljak:
> I'd like to add that, to me, the difference between stable and unstable
> version is obvious enough if I see v2.8.0-alpha1, 2.8.0-alpha2,
> 2.8.0-beta1, 2.8.0-rc1, and then 2.8.0. I see no need for separate version
> numbers.

That's a good point. I should check though whether our build system can handle 
this. If it does or if we can make it so, using explicit alpha/beta/rc strings 
would be very clear. It would be also require some getting used to as until 
now we never made an explicit distinction between alpha/beta/rc (though we 
imply it sometimes in warnings). Should we ? And if so, what would be the 
criterion ?

To widen the scope here, I would eventually like to get to a point where 
master (or at least unstable) is always in an almost releasable state. All 
work that's not in that state should be on feature branches. That would then 
make any release we'd make a potential release candidate. But we're far from 
that IMO, because our test coverage is not sufficient to confidently assume 
big changes don't break other parts of the code.

> However, I don't feel strongly about the version numbers as long as they
> make sense. The above is just something I'd instinctively recognise if I
> did not know absolutely anything else about the project at hand. 
> The same goes for major/minor version. For example, in the projects I
> contribute to (at work or privately), I tend to continuously update any
> dependencies that have minor version updates, assuming they contain only
> minor improvements. Bug fixes (the third number) are almost mandatory
> updates as they often correct issues that we identify ourselves. Major
> version change requires more time and effort in checking what has changed
> and hence doesn't get updated readily. That usually involves a migration
> path and coordinated effort. All this information is fairly obvious from
> just those three numbers. 

Indeed. I have been pondering this in the gnucash project. A 3 number 
versioning scheme that adheres to this would also mean we'd need not one but 
two maintenance branches: one for bugfixes and one for backwards compatible 
new features. (And all bugfixes would be upmerged into the the backwards 
compatible new features branch but not the other way around). Given the small 
size of our team I'm not sure the extra effort would be justified for the net 
gain. If gnucash were a public library I would probably more conservative.

Regards,

Geert
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Beyond 2.8 - some design thoughts

[Alen Siljak]

   I'd like to add that, to me, the difference between stable and unstable
   version is obvious enough if I see v2.8.0-alpha1, 2.8.0-alpha2,
   2.8.0-beta1, 2.8.0-rc1, and then 2.8.0. I see no need for separate
   version numbers.

   However, I don't feel strongly about the version numbers as long as
   they make sense. The above is just something I'd instinctively
   recognise if I did not know absolutely anything else about the project
   at hand.

   The same goes for major/minor version. For example, in the projects I
   contribute to (at work or privately), I tend to continuously update any
   dependencies that have minor version updates, assuming they contain
   only minor improvements. Bug fixes (the third number) are almost
   mandatory updates as they often correct issues that we identify
   ourselves.
   Major version change requires more time and effort in checking what has
   changed and hence doesn't get updated readily. That usually involves a
   migration path and coordinated effort.
   All this information is fairly obvious from just those three numbers.

   Happy New Year!

   Sent: Wednesday, December 27, 2017 at 6:15 PM
   From: "Geert Janssens" <geert.gnuc...@kobaltwit.be>
   To: gnucash-devel@gnucash.org
   Cc: "Alen Siljak" <alen.sil...@gmx.com>
   Subject: Re: Beyond 2.8 - some design thoughts
   I do agree up to some point. I consider the scheme I propose to be
   mostly a
   simplified form of the semantic versioning. We will use one level less,
   because we don't distinguish between bugfixes and compatible features.
   I can
   understand why this is suggested for libraries. The reality is we
   haven't been
   doing this for years. Also with every major release (2.6.0, 2.8.0,...)
   we have
   been introducing backwards incompatible changes. According to the
   semantic
   versioning this means we should have updated the first number rather
   than the
   second one. So applying the rules of semantic versioning on gnucash in
   the
   past would have been misleading.
   Geert
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Beyond 2.8 - some design thoughts

[Geert Janssens]

Op woensdag 27 december 2017 12:51:32 CET schreef Wm via gnucash-devel:
> On 24/12/2017 16:34, Geert Janssens wrote:
> 
> [snips below, hopefully context maintained]
> 
> > 1. Use of namespaces.
> > 
> > For 2.8 I have been working on converting parts of the CSV importer to
> > C++.
> > And considering the class structure that is slowly forming there (still in
> > flux as conversion of additional importers reveals design limitations that
> > shouldn't be there) I am even tempted to use nested namespaces there (not
> > nested classes, mind you) like
> > 
> > On the other hand I don't have much experience with namespaces yet (other
> > than using st:: and boost:: which have nested namespaces as well) so I
> > don't know the pro's and con's of it. So I'm interested in opinions about
> > this.
> I'm not sure what most people consider CSV accounting data is useful to
> begin with, although I also know it can't be ignored entirely.
> 
> The ever-improvement of the csv import is a project that will always
> fail, it happens every time someone exports a csv file from their
> accounting program / spreadsheet and the gnc import doesn't say "hooray,
> I love your format, we bow to your format". 

Whether it's a useful format or not is not too important. It is pretty 
universal though and a generic  export format available in many accounting 
packages, including online banking sites. For that reason alone we have to 
support it.

It comes in many variations though so it is likely some tweaking will always 
be necessary. What I aimed for in the new csv importer is to make fewer 
assumptions on what the exact format of a csv file is. The importer is now 
configurable with live preview.

I agree we'll probably never be able to support all exotic flavors of the csv 
format. But if I can tip the balance from 80% of the users has to preprocess 
their csv file to 20% have to, that's a win for gnucash in my opinion.

> I suggest a presumed import
> format of ledger-cli type data and levering the work of shared open
> source accounting data.  Writing a script to get from a csv into
> ledger-cli is transparent, portable and useful to a broad community.
> 
A ledger-cli type data import would surely be welcome.

On the other hand not all of our users would be capable of writing such a 
script. It would shift the burden of getting the tweak the csv file for 
usefulness one level up, namely to get it to convert into ledger-cli format. 
So there also each possible variation has to be taken into account. So in the 
end I don't see how this would make things easier for the end user.

> > 2. Versioning.
> > 
> > The migration to gtk2 has been a long
> > time ago and the software world has evolved since then. Release cycles in
> > general have shortened. Incremental changes are usually preferred over big
> > bang changes. So I think our numbering scheme is in for a modernization.
> 
> gnc's versioning does seem dated although I expect people that read the
> dev list may be used to them by now.
> 
> As someone less involved in gnc coding but with a lot of interest in
> data I'd have thought the next non-backward compatible format change
> would be the next gigantic.

Ok, which is more or less what my proposal achieves.

Geert

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Beyond 2.8 - some design thoughts

[Geert Janssens]

Op maandag 25 december 2017 01:49:41 CET schreef Alen Siljak:
> To me, as an outsider and an occassional tester, Semantic Versioning would
> make much more sense than any other custom versioning system. Simply
> because it is getting common across various software packages and
> libraries. It might work for the GUI application as well, when referring to
> the workflows instead of APIs. In that regard, I would always go for the
> "don't make me think" approach and stay away from numbering schemes that
> require a user manual to figure out. 
> There's an answer on Stack Exchange that explains this into more detail:
> https://softwareengineering.stackexchange.com/questions/255190/how-does-sem
> antic-versioning-apply-to-programs-without-api 
> 
I do agree up to some point. I consider the scheme I propose to be mostly a 
simplified form of the semantic versioning. We will use one level less, 
because we don't distinguish between bugfixes and compatible features. I can 
understand why this is suggested for libraries. The reality is we haven't been 
doing this for years. Also with every major release (2.6.0, 2.8.0,...) we have 
been introducing backwards incompatible changes. According to the semantic 
versioning this means we should have updated the first number rather than the 
second one. So applying the rules of semantic versioning on gnucash in the 
past would have been misleading.

Geert
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Beyond 2.8 - some design thoughts

[Wm via gnucash-devel]

On 24/12/2017 16:34, Geert Janssens wrote:

[snips below, hopefully context maintained]


1. Use of namespaces.



For 2.8 I have been working on converting parts of the CSV importer to C++.
And considering the class structure that is slowly forming there (still in
flux as conversion of additional importers reveals design limitations that
shouldn't be there) I am even tempted to use nested namespaces there (not
nested classes, mind you) like



On the other hand I don't have much experience with namespaces yet (other than
using st:: and boost:: which have nested namespaces as well) so I don't know
the pro's and con's of it. So I'm interested in opinions about this.


I'm not sure what most people consider CSV accounting data is useful to 
begin with, although I also know it can't be ignored entirely.


The ever-improvement of the csv import is a project that will always 
fail, it happens every time someone exports a csv file from their 
accounting program / spreadsheet and the gnc import doesn't say "hooray, 
I love your format, we bow to your format".  I suggest a presumed import 
format of ledger-cli type data and levering the work of shared open 
source accounting data.  Writing a script to get from a csv into 
ledger-cli is transparent, portable and useful to a broad community.


It also means only one significant import / transfer format for gnc and 
related software to concentrate on <-- very good thing.




2. Versioning.



The migration to gtk2 has been a long
time ago and the software world has evolved since then. Release cycles in
general have shortened. Incremental changes are usually preferred over big
bang changes. So I think our numbering scheme is in for a modernization.


gnc's versioning does seem dated although I expect people that read the 
dev list may be used to them by now.


As someone less involved in gnc coding but with a lot of interest in 
data I'd have thought the next non-backward compatible format change 
would be the next gigantic.


--
Wm

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Beyond 2.8 - some design thoughts

[John Ralls]

> On Dec 25, 2017, at 9:24 AM, Geert Janssens  
> wrote:
> 
> Op maandag 25 december 2017 17:34:22 CET schreef Christian Stimming:
>> As for the namespace aliases such as "namespace gia =
>> gnc::import::aqbanking", those must not appear in header files, but may
>> appear in cpp files. However, I didn't like those in general, as it makes
>> readability for other people much harder. In terms of mutual readability of
>> code, I would rather stick to the plain namespace names and that's it.
>> 
> Ok. I know we are using them in our new c++ code when referencing certain 
> boost namespaces. And the readability aspect works both ways. If namespaces 
> get too long, the code becomes hard to read as well. I have found my IDE 
> (kdevelop currently) quite helpful in deciphering the aliases. I'm not sure 
> which way I like best currently.

I used them in GncDateTime because the boost::date_time developer got carried 
away in exactly the way I warned against. Those aliases are in a single 
implementation file that’s intended to hide the implementation details from the 
rest of GnuCash.

There’s another use of aliases that does belong in headers: Declaring a 
pseudo-type for container classes. For example, from gnc-backend-sql.hpp:

using VersionPair = std::pair;
using VersionVec = std::vector;

helps express the container’s intended use (a vector of version tags) and is 
much more readable in code than writing std::vector> all over the place.

Regards,
John Ralls
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Beyond 2.8 - some design thoughts

[Geert Janssens]

Op maandag 25 december 2017 17:34:22 CET schreef Christian Stimming:
> Hi Geert,
> 
> just two bits of thoughts from my side:
> 
> Am Sonntag, 24. Dezember 2017, 17:34:51 schrieb Geert Janssens:
> > 1. Use of namespaces.
> > ... nested namespaces ...
> 
> Yes, absolutely. I have quite some experience with C++ libraries and
> applications and I made very positive experience with this scheme. In our
> case this means we put all of our code in a "gnc::" namespace (at least).
> 
> For me, the nicest way to write this was indeed to wrap the content of every
> file by "namespace gnc {" and "}" (except for the #include directives and
> such). There are some examples - but very few - where some other code
> requires us to put code from us in other namespaces, such as some io
> modifiers, or operators for std classes, but this is then clearly visible.
> 
> Nevertheless "using namespace gnc" should rather not be used, as it makes
> the point of namespaces quite moot, as John already said.
> 
Ok, I can live with this as well.

> Also, if there is some sort of "modules" that are used in some places but
> not everywhere, it is also useful to add another level of sub-namespace.
> Such as "gnc::import::", but maybe not quite the "engine", as it is used
> throughout everywhere of our code anyway.
> 
Agreed, adding an "engine" sub-namespace would not add much.

> If there are any nested namespaces, I would strongly recommend to match the
> namespace structure also in the directory names, at least the topmost ones.
> In our case this implies to match this also in the gnc-modules structure.
> 
Good point.

> Apart from this, and for the project of our size, we might very well not
> need more than two levels of namespaces.
> 
Agreed.

> As for the namespace aliases such as "namespace gia =
> gnc::import::aqbanking", those must not appear in header files, but may
> appear in cpp files. However, I didn't like those in general, as it makes
> readability for other people much harder. In terms of mutual readability of
> code, I would rather stick to the plain namespace names and that's it.
> 
Ok. I know we are using them in our new c++ code when referencing certain 
boost namespaces. And the readability aspect works both ways. If namespaces 
get too long, the code becomes hard to read as well. I have found my IDE 
(kdevelop currently) quite helpful in deciphering the aliases. I'm not sure 
which way I like best currently.

Geert


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Beyond 2.8 - some design thoughts

[Geert Janssens]

Op maandag 25 december 2017 00:34:39 CET schreef John Ralls:
> > On Dec 24, 2017, at 8:34 AM, Geert Janssens 
> > wrote:
> > 
> > 2. Versioning.
> > 
> > We currently use a version scheme gigantic.major.minor[-build]. Like
> > 2.6.19
> > (and an optional -2 if we had to release more than once to get it right).
> > For the 3 levels we really only use two. The 2 in front has been updated
> > when gnucash migrated from gtk to gtk2.  We will migrate to gtk3 for
> > gnucash 2.8 yet we don't changed to 3.0 as a result. The migration to
> > gtk2 has been a long time ago and the software world has evolved since
> > then. Release cycles in general have shortened. Incremental changes are
> > usually preferred over big bang changes. So I think our numbering scheme
> > is in for a modernization.
> > 
> > Here's my proposal:
> > After the 2.8 lifecycle let's drop one number and stick with major.minor[-
> > build] instead.
> > Major releases would increment the first number. Bugfix releases the
> > second.
> > 
> > So after 2.8 the next major release would be 3.0, bugfix releases for that
> > major release would become 3.1, 3.2, 3.4...
> > 
> > I would drop the idea of odd numbers being development snapshots and even
> > numbers being stable ones. Instead I see several options, I haven't
> > decided
> > which one is most elegant/kludgy:
> > 
> > Option A: let's number development snapshots starting from x.90. That
> > gives us 10 development snapshots. If that's not enough we can either
> > choose to start a bit earlier, like x.80 or from x.98 jump to x.980 to
> > give us 20 more. Option B: as a variation all development snapshots do
> > use a 3 number version: x.99.z with 99 clearly indicating "right before
> > the next major release" and z incrementing with each snapshot.
> > 
> > This makes development snapshots slightly more verbose in their numbering
> > but gives us cleanly incrementing stable releases. The latter are more
> > visible to most users, so I personally care more about those.
> > 
> > The development snapshots between 2.8 and 3.0 fall a bit in between. We
> > could choose to handle them old style or new style as we see fit. Old
> > style would mean we'd still work with a 2.9.x series. New style would
> > mean we'd start with 2.8.90/2.8.99.1 as we see fit.
> > 
> > Thoughts ?
> 
> I’m indifferent to the versioning system as long as it’s consistent, but the
> distro packagers aren’t. Some of them recite the “Semantic Versioning” [1]
> mantra even though it really applies only to libraries.
> 
Interesting link though it does indeed target mostly libraries. The Stack 
Exchange link [1] Alen Siljak posted in his reply also suggests semantic 
versioning. However at the same time one of the (highly ranked) answers on 
that page does give reasons why applications may choose not to follow this 
scheme.

I've also read the semantic versioning scheme and I think we have been 
ignoring the distinction between minor and micro for a long time and are 
really using their minor number as our major one. We don't really expose an 
api right now, but we allow things like incompatible config file or data file 
changes only in what we call a major release (like 2.6.0, 2.8.0). We don't 
make a distinction between adding smaller features and bugfixes as long as 
they don't break compatibility. So to my mind our versioning would be semantic 
as well, but with one level of detail less.

> Back when we released 2.6 we were unsure about whether the coming version
> would be 2.8 or 3.0. One of the criteria proposed was that we should call
> it 3.0 if we upgraded to Gtk+3. Well, we have, so maybe the coming release
> should be 3.0.0 instead of 2.8.0. That would certainly be consistent with
> the Gnome guidelines [2] that include a major change in the GUI as a reason
> for bumping the major version.

We could, though I'm not really married to Gnome's guidelines. Also I don't 
really follow the idea of big-bang releases. I'm more in favor of steady, 
incremental development. Having a different number for major changes grows 
wrong user expectations (or disappointments if that number is not changed for 
sufficiently long enough). Simply increasing one number just indicates there's 
progress.

> 
> Should some of the component libraries (especially libgnucash) have separate
> versioning that follows the semantic versioning rules?

Now that is an interesting question. Perhaps we should as soon as libgnucash 
is something worth mentioning on its own and I think even then only if we will 
consider releasing them independently.

And regardless I'd still be fine with a two-number scheme as it reflects our 
development practises more closely than a 3-number one.

If we go for separate versioning at some point I'd make gnucash follow the 
major version of libgnucash.

Lastly, while reading the two links you added I found the even/odd distinction 
is not mentioned at all in semantic versioning but instead is an 

Re: Beyond 2.8 - some design thoughts

[Christian Stimming]

Hi Geert,

just two bits of thoughts from my side:

Am Sonntag, 24. Dezember 2017, 17:34:51 schrieb Geert Janssens:
> 1. Use of namespaces.
> ... nested namespaces ...

Yes, absolutely. I have quite some experience with C++ libraries and 
applications and I made very positive experience with this scheme. In our case 
this means we put all of our code in a "gnc::" namespace (at least). 

For me, the nicest way to write this was indeed to wrap the content of every 
file by "namespace gnc {" and "}" (except for the #include directives and 
such). There are some examples - but very few - where some other code requires 
us to put code from us in other namespaces, such as some io modifiers, or 
operators for std classes, but this is then clearly visible. 

Nevertheless "using namespace gnc" should rather not be used, as it makes the 
point of namespaces quite moot, as John already said.

Also, if there is some sort of "modules" that are used in some places but not 
everywhere, it is also useful to add another level of sub-namespace. Such as 
"gnc::import::", but maybe not quite the "engine", as it is used throughout 
everywhere of our code anyway.

If there are any nested namespaces, I would strongly recommend to match the 
namespace structure also in the directory names, at least the topmost ones. In 
our case this implies to match this also in the gnc-modules structure.

Apart from this, and for the project of our size, we might very well not need 
more than two levels of namespaces.

As for the namespace aliases such as "namespace gia = gnc::import::aqbanking", 
those must not appear in header files, but may appear in cpp files. However, I 
didn't like those in general, as it makes readability for other people much 
harder. In terms of mutual readability of code, I would rather stick to the 
plain namespace names and that's it.

> 2. Versioning.
> Here's my proposal:
> After the 2.8 lifecycle let's drop one number and stick with major.minor[-
> build] instead.
> Major releases would increment the first number. Bugfix releases the second.

+1 from me.

Regards,

Christian

___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Beyond 2.8 - some design thoughts

[Alen Siljak]

   To me, as an outsider and an occassional tester, Semantic Versioning
   would make much more sense than any other custom versioning system.
   Simply because it is getting common across various software packages
   and libraries. It might work for the GUI application as well, when
   referring to the workflows instead of APIs.
   In that regard, I would always go for the "don't make me think"
   approach and stay away from numbering schemes that require a user
   manual to figure out.

   There's an answer on Stack Exchange that explains this into more
   detail:
   https://softwareengineering.stackexchange.com/questions/255190/how-does
   -semantic-versioning-apply-to-programs-without-api

   >
   > Option A: let's number development snapshots starting from x.90. That
   gives us
   > 10 development snapshots. If that's not enough we can either choose
   to start a
   > bit earlier, like x.80 or from x.98 jump to x.980 to give us 20 more.
   > Option B: as a variation all development snapshots do use a 3 number
   version:
   > x.99.z with 99 clearly indicating "right before the next major
   release" and z
   > incrementing with each snapshot.
   >
   I’m indifferent to the versioning system as long as it’s consistent,
   but the distro packagers aren’t. Some of them recite the “Semantic
   Versioning” [1] mantra even though it really applies only to libraries.
   Back when we released 2.6 we were unsure about whether the coming
   version would be 2.8 or 3.0. One of the criteria proposed was that we
   should call it 3.0 if we upgraded to Gtk+3. Well, we have, so maybe the
   coming release should be 3.0.0 instead of 2.8.0. That would certainly
   be consistent with the Gnome guidelines [2] that include a major change
   in the GUI as a reason for bumping the major version.
   Should some of the component libraries (especially libgnucash) have
   separate versioning that follows the semantic versioning rules?
   Regards,
   John Ralls
   [1] [1]https://semver.org/ <[2]https://semver.org/>[2]
   [3]https://developer.gnome.org/programming-guidelines/stable/versioning
   .html.en
   <[4]https://developer.gnome.org/programming-guidelines/stable/versionin
   g.html.en>

References

   1. https://semver.org/
   2. https://semver.org/
   3. 
https://developer.gnome.org/programming-guidelines/stable/versioning.html.en
   4. 
https://developer.gnome.org/programming-guidelines/stable/versioning.html.en
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Re: Beyond 2.8 - some design thoughts

[John Ralls]

> On Dec 24, 2017, at 8:34 AM, Geert Janssens  
> wrote:
> 
> While we're working hard to get 2.8 ready for official release, the current 
> state of the code keeps reminding me of a few design related topics I would 
> like to discuss for the development cycle after 2.8 has been released.
> 
> We're still a few months away from that point, but it's a quiet Christmas eve 
> so I am feeling like sharing this already for further discussion.
> 
> 1. Use of namespaces.
> 
> Our current code is full of Gnc for types and gnc_ 
> for functions. In our C++ rewrite we're replacing this with classes of type 
> Gnc and so on. I would like to propose we introduce a 'gnc' 
> namespace (at least in libgnucash) so our classes become gnc::. 
> This is consistent with std:: and boost:: namespaces.

+1

> 
> We can debate whether our internal code can/should have "namespace gnc;" in 
> headers only or in source files as well. For libgnucash I'd go for the 
> latter. 
> It  The context should be clear there. In the gnucash gui related code (the 
> parts that are C++ obviously), I would as well, though I have a less strong 
> opinion there.

I don’t think you meant what you said there because I know that you know that 
once you declare something in a namespace you have to either refer to it with 
the namespace qualifier everywhere or alias it in to the scope’s namespace with 
‘using’.

Perhaps you mean that you’re not sure if compilation-unit-local functions and 
variables (those typically declared static in C) should also be in the gnc 
namespace. I don’t think so. There’s a special compilation-unit-local namespace 
called the anonymous namespace for that.

Should the gnc namespace be applied to classes throughout the application or 
just to libgnucash classes? I’m inclined to think the latter. The application 
itself doesn’t really benefit from a namespace though some of its modules 
might. Your division of the code into libgnucash and gnucash is a first good 
cut but I’m sure we agree that it’s going to need refining in the next 
development cycle. Working out namespace divisions can help with that 
refinement because the namespaces will make logical groupings more apparent.

> For 2.8 I have been working on converting parts of the CSV importer to C++. 
> And considering the class structure that is slowly forming there (still in 
> flux as conversion of additional importers reveals design limitations that 
> shouldn't be there) I am even tempted to use nested namespaces there (not 
> nested classes, mind you) like
> namespace gnc
> {
> 
> namespace import
> 
> class settings
> ...
> 
> }
> }
> 
> I personally like the granularity and grouping effect this has. In addition 
> it 
> makes the actual actions related to a namespace stand out nicely
> gnc::import::settings::get_presets()
> Which with a 'using gis = gnc::import::settings' could be reduced to 
> 'gis::get_presets()' if one likes.
> 
> On the other hand I don't have much experience with namespaces yet (other 
> than 
> using st:: and boost:: which have nested namespaces as well) so I don't know 
> the pro's and con's of it. So I'm interested in opinions about this.

Namespaces are a Good Thing™ but it’s easy to get carried away with nesting too 
deeply just as it’s easy to get carried away with deep class hierarchies. 
Aliases help as long as we’re consistent about alias names so that one doesn’t 
have to keep track of different aliases for the same class when working across 
two or three files. One can also import whole namespaces (`using namespace 
gnc;`) but that’s discouraged as it rather defeats the point of using 
namespaces.

> 
> 
> 2. Versioning.
> 
> We currently use a version scheme gigantic.major.minor[-build]. Like 2.6.19 
> (and an optional -2 if we had to release more than once to get it right). For 
> the 3 levels we really only use two. The 2 in front has been updated when 
> gnucash migrated from gtk to gtk2.  We will migrate to gtk3 for gnucash 2.8 
> yet we don't changed to 3.0 as a result. The migration to gtk2 has been a 
> long 
> time ago and the software world has evolved since then. Release cycles in 
> general have shortened. Incremental changes are usually preferred over big 
> bang changes. So I think our numbering scheme is in for a modernization.
> 
> Here's my proposal:
> After the 2.8 lifecycle let's drop one number and stick with major.minor[-
> build] instead. 
> Major releases would increment the first number. Bugfix releases the second.
> 
> So after 2.8 the next major release would be 3.0, bugfix releases for that 
> major release would become 3.1, 3.2, 3.4...
> 
> I would drop the idea of odd numbers being development snapshots and even 
> numbers being stable ones. Instead I see several options, I haven't decided 
> which one is most elegant/kludgy:
> 
> Option A: let's number development snapshots starting from x.90. That gives 
> us 
> 10 development snapshots. If that's not enough we 

Beyond 2.8 - some design thoughts

[Geert Janssens]

While we're working hard to get 2.8 ready for official release, the current 
state of the code keeps reminding me of a few design related topics I would 
like to discuss for the development cycle after 2.8 has been released.

We're still a few months away from that point, but it's a quiet Christmas eve 
so I am feeling like sharing this already for further discussion.

1. Use of namespaces.

Our current code is full of Gnc for types and gnc_ 
for functions. In our C++ rewrite we're replacing this with classes of type 
Gnc and so on. I would like to propose we introduce a 'gnc' 
namespace (at least in libgnucash) so our classes become gnc::. 
This is consistent with std:: and boost:: namespaces.

We can debate whether our internal code can/should have "namespace gnc;" in 
headers only or in source files as well. For libgnucash I'd go for the latter. 
It  The context should be clear there. In the gnucash gui related code (the 
parts that are C++ obviously), I would as well, though I have a less strong 
opinion there.

For 2.8 I have been working on converting parts of the CSV importer to C++. 
And considering the class structure that is slowly forming there (still in 
flux as conversion of additional importers reveals design limitations that 
shouldn't be there) I am even tempted to use nested namespaces there (not 
nested classes, mind you) like
namespace gnc
{

namespace import

class settings
...

}
}

I personally like the granularity and grouping effect this has. In addition it 
makes the actual actions related to a namespace stand out nicely
gnc::import::settings::get_presets()
Which with a 'using gis = gnc::import::settings' could be reduced to 
'gis::get_presets()' if one likes.

On the other hand I don't have much experience with namespaces yet (other than 
using st:: and boost:: which have nested namespaces as well) so I don't know 
the pro's and con's of it. So I'm interested in opinions about this.


2. Versioning.

We currently use a version scheme gigantic.major.minor[-build]. Like 2.6.19 
(and an optional -2 if we had to release more than once to get it right). For 
the 3 levels we really only use two. The 2 in front has been updated when 
gnucash migrated from gtk to gtk2.  We will migrate to gtk3 for gnucash 2.8 
yet we don't changed to 3.0 as a result. The migration to gtk2 has been a long 
time ago and the software world has evolved since then. Release cycles in 
general have shortened. Incremental changes are usually preferred over big 
bang changes. So I think our numbering scheme is in for a modernization.

Here's my proposal:
After the 2.8 lifecycle let's drop one number and stick with major.minor[-
build] instead. 
Major releases would increment the first number. Bugfix releases the second.

So after 2.8 the next major release would be 3.0, bugfix releases for that 
major release would become 3.1, 3.2, 3.4...

I would drop the idea of odd numbers being development snapshots and even 
numbers being stable ones. Instead I see several options, I haven't decided 
which one is most elegant/kludgy:

Option A: let's number development snapshots starting from x.90. That gives us 
10 development snapshots. If that's not enough we can either choose to start a 
bit earlier, like x.80 or from x.98 jump to x.980 to give us 20 more.
Option B: as a variation all development snapshots do use a 3 number version: 
x.99.z with 99 clearly indicating "right before the next major release" and z 
incrementing with each snapshot.

This makes development snapshots slightly more verbose in their numbering but 
gives us cleanly incrementing stable releases. The latter are more visible to 
most users, so I personally care more about those.

The development snapshots between 2.8 and 3.0 fall a bit in between. We could 
choose to handle them old style or new style as we see fit. Old style would 
mean we'd still work with a 2.9.x series. New style would mean we'd start with 
2.8.90/2.8.99.1 as we see fit.

Thoughts ?


Other than that,

Merry Christmas to all!

Geert
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel