Beyond 2.8 - some design thoughts
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
Re: Beyond 2.8 - some design thoughts
> 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 can either choose to start
>
Re: Beyond 2.8 - some design thoughts
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
