AGS 3.3.x/3.4.0.0 Developer Discussion

Started by Gurok, Sun 09/02/2014 08:45:13

Previous topic - Next topic

Crimson Wizard

#140
Quote from: BigMc on Fri 19/09/2014 19:30:11
And while we're at it... Since you are releasing preview binary releases (alpha,beta,rc..), I think it would be a good idea to give them also proper version numbers. The approach that is most compatible with sortability of versions is to give odd numbers to development versions and even numbers to stable releases, e.g. call the development branch now 3.5 and let that turn into the stable release 3.6. This approach is for example used by Allegro and the Linux kernel.
Hmm, we are doing this, just changing the last (fourth) build number before every update (using odd numbers for development branch). Is not that enough?
I am afraid that unlike developers most common users will be confused if main numbers will be jumping between release versions, will look for intermediate versions etc.

BigMc

Look for example at the Allegro homepage: http://alleg.sourceforge.net/
It's all pretty clear isn't it?

I think most users get AGS from the homepage where only stable releases are found or not?

Crimson Wizard

#142
Quote from: BigMc on Fri 19/09/2014 20:01:53
Look for example at the Allegro homepage: http://alleg.sourceforge.net/
It's all pretty clear isn't it?
Not sure... maybe I do not get something?
Don't we have same thing know, there's 3.3.0.* with hotfixes and 3.3.1.* in development? Is there a big difference?

E: I need to think a bit about this....

Quote from: BigMc on Fri 19/09/2014 20:01:53
I think most users get AGS from the homepage where only stable releases are found or not?
I mean, we will have to explain why the previous version was 3.4 and new one suddenly 3.6. Your examples are both low-level developer tools, and AGS is a common user product.

BigMc

Anyway, I like that scheme. It's a matter of taste. AGS is also for developers...

Gurok

Should I rename the 3.3.1 threads to 3.4.0? I've been thinking about it, but I don't want to cause confusion with the _other_ 3.4.0.
[img]http://7d4iqnx.gif;rWRLUuw.gi

Crimson Wizard

We need to get to conclusion on version numbering first. Let me think till tomorrow, I want to consider what BigMC said.

As for "another 3.4.0", I doubt it is really used for any project right now. It was an experimental build with temporary name.

monkey0506

Quote from: Crimson Wizard on Fri 19/09/2014 20:17:11I mean, we will have to explain why the previous version was 3.4 and new one suddenly 3.6. Your examples are both low-level developer tools, and AGS is a common user product.

I agree with this. I think that in general the way the versioning is controlled now is appropriate. The way it's worked thus far, the first version number has actually corresponded exactly to major editor revisions (e.g., complete IDE rewrite). The secondary version number is generally increased when there are major changes to the editor or engine (script API changes, major bugfixes, etc.). The tertiary version number is then reserved for more minor changes, minor bugfixes, minor feature fixes, and the like. This all applies directly to the public release version numbers, and I think it works very well. The fourth version number being used to differentiate between development revisions (using even numbers for stable releases) also serves its purpose.

That being said, it may not be immediately obvious how the versioning works. Is this actually documented explicitly anywhere?

BigMc

Quote from: monkey_05_06 on Sat 20/09/2014 04:15:54
The way it's worked thus far, the first version number has actually corresponded exactly to major editor revisions (e.g., complete IDE rewrite). The secondary version number is generally increased when there are major changes to the editor or engine (script API changes, major bugfixes, etc.). The tertiary version number is then reserved for more minor changes, minor bugfixes, minor feature fixes, and the like. This all applies directly to the public release version numbers, and I think it works very well.

That would all stay the same with the scheme I proposed, except that builds coming from a development branch would have the secondary version odd (and maybe a beta, rc, wip or whatever suffix to clarify) and builds from a stable branch have an even secondary version. Both increase once the development branch turns into a stable branch, i.e. a new major stable version is released.

Crimson Wizard

#148
Quote from: monkey_05_06 on Sat 20/09/2014 04:15:54The fourth version number being used to differentiate between development revisions (using even numbers for stable releases) also serves its purpose.
It appears to me that it's not used that properly; in fact I started to use it so after incorrectly understanding BigMC's suggestion when he made it first time (about a year ago).

Quote from: monkey_05_06 on Sat 20/09/2014 04:15:54
That being said, it may not be immediately obvious how the versioning works. Is this actually documented explicitly anywhere?
This might have been mentioned in few topics, I found an indirect reference here:
http://www.adventuregamestudio.co.uk/forums/index.php?topic=50001.0
And also this was the very first thread we discussed version numbers:
http://www.adventuregamestudio.co.uk/forums/index.php?topic=47581.0
//-----------------------------------------------------------------------------



Now, I took some time to think this over, and I should say that I saw logic in what BigMCs suggestion. Of course, that may be uncommon for AGS users.
Following is my IMHO.

What do we need version for? To let people know their order and meaning (major change, minor change).
Every public release, whether alpha, beta or final, should have distinct version visible to users (i.e. no hidden numbers, internal tags).

If we are working on version 1.2 and make beta releases, we must change version somehow, for example add the third number: 1.2.1 is first beta, 1.2.2 is second beta, and so forth.
When we release a final/stable version, we need to somehow emphasize that this is the next stage of a program, not WIP/beta anymore. If we just increase auxiliary number one more time (e.g. make it 1.2.3), we won't achieve this, because it will blend with WIP versions.
For the very first alpha/betas developers often use numbers starting with 0 (e.g. 0.5.1); however, this can hardly work for the next versions.

AGS has a tradition of X.Y.Z stable releases (generation, major, minor), but also has the fourth number, which was used only for internal purposes. In the times of SVN repository this number was probably equal to SVN revision (commit) number. Today it lost its meaning, because:
- in Git there's no commit number, there's commit hash (which lets to identify particular commit, but, unfortunately, does not tell anything about its order);
- public releases require a change of one of the "public" numbers;
- developers and repo users does not need this "internal" number either, because they know which commit they used to build the program.
- when there are at least two branches, both of which may have public updates, it is impossible to have a single sequence of "revision" numbers in a proper order.

//---------------------------------------------------

The conclusion:

1. Version should visibly change at every public release. By "visibly change" I mean that the end-user should be aware of numbers, and their meaning and order should be clear to him/her.
2. We would benefit from distinct change in numbers when WIP version changes to stable version.
3. The fourth version number lost its meaning and should be either removed, or utilized differently.
4. The upcoming 3.4.0 version may be the starting point of introducing new version numbering (whichever is chosen).

//---------------------------------------------------

What is the solution referenced by BigMC? It is to make the version number increase every time we move from stable to WIP and back to stable. For example:

3.4 is stable version and 3.4.* are stable version updates
3.5 is a WIP version and 3.5.* are WIP updates; when 3.5 is completed, it is changed to stable 3.6.0, and next WIP is 3.7.0 (started simultaneosly).

Optionally, if we are using three numbers for stable release and fourth number for updates:

3.4 is a major stable version and 3.4.0.* are stable version updates
3.4.1 is a minor WIP version and 3.4.1.* are its updates. When 3.4.1 is completed, it is changed to stable 3.4.2, and next WIP could be 3.4.3.
3.5 is a major WIP version (same as above), which will end as 3.6, the next major stable version.



What are alternative solutions? I know only one: stable version updates follow up WIP versions, for example:

3.4.0 is the alpa, 3.4.1, 3.4.2 are betas, 3.4.3 is the first stable release. This won't cause "jumps" between stable releases, but change between WIP and stable will be less distinct. Whether it is a problem or not is a subjective question, IMO.

EDIT: if we use fourth number, then, for example, 3.4.0.0 -> 3.4.0.4 are betas and 3.4.0.5 is first stable. This keeps the first three numbers the same as end-user would expect, and utilizes fourth number as "developer update". But it must be included to package name.
Actually, thinking more about this, I like four-numbers sequence better.


What do you think?

Alberth

I wonder what 3.5.2 is, a stable WIP version???

I know projects do even/odd numbering, but I have never seen it applied at sub-number level yet. I believe most users will not understand that 3.4.3 is a WIP, and they should instead download 3.4.2. The usual idea is "higher number  == better".


Why not make unstable versions explicit?  3.4.2-beta1 (or -wip or -rc or -dev), 3.4.2-beta2 ... to release 3.4.2, with updates or fixes 3.4.2.1 , 3.4.2.2 etc.
After 3.4.2, develop 3.4.3-beta1.  You could use different suffixes for different goals, 'beta' or 'wip' for just an intermediate version, 'rc' for a test build of the next stable (ie no big new things will be added before the release). Don't know if you need that, it may add very little, yet adds to the complexity of releases.

After reading your older post about branches http://www.adventuregamestudio.co.uk/forums/index.php?topic=50001.0, I think 'develop' itself should not have a version number at all, you could use 0.0.0.<git-hash> if you need to build it.
A version number (like 3.4.2 or 3.4.3-beta1) should be decided in the release branch, where you (in my opinion) can pick any number bigger than what you have already released. For example, if a huge new feature is added after 3.4.3-beta1, you could jump to 3.5-beta1 or even 4.0-beta1 (assuming you always have 2 numbers at least). Another option is to make such number decisions just before the next release, and not before (ie keep 3.4.3-betaX no matter what is added). That may be easier for the release process and less confusing for people to follow.

I am still puzzled by the 'master' branch. Suppose 2.6.4 has been released. It's on the master branch. Next I bring out 3.7, and then find a bug in 2.6.4. Where would 2.6.5 go? It seems to me the 'master' branch is making things complicated if you have several release branches in parallel. Is there anything wrong with just making a branch off develop for every major new version (say 3.4), and update that branch to 3.4.1 etc ?
(Just puzzling why the 'master' exists, from a release theoretic point of view, if you don't need the extra complexity, by all means keep what works for you.)

Crimson Wizard

#150
Quote from: Alberth on Sat 20/09/2014 16:53:35
After reading your older post about branches http://www.adventuregamestudio.co.uk/forums/index.php?topic=50001.0, I think 'develop' itself should not have a version number at all, you could use 0.0.0.<git-hash> if you need to build it.
This is the question of public version, not naming the branch. The branch can be named in any way which is convinient for developers; and if developers make some build for themselves, they can again call it as they please. However here we discuss the version as seen by users; and release version should have clear meaning for them. End-users don't know what "git-hash" is, how will they know this version is the next beta or whatnot?


Quote from: Alberth on Sat 20/09/2014 16:53:35
I am still puzzled by the 'master' branch. Suppose 2.6.4 has been released. It's on the master branch. Next I bring out 3.7, and then find a bug in 2.6.4. Where would 2.6.5 go? It seems to me the 'master' branch is making things complicated if you have several release branches in parallel. Is there anything wrong with just making a branch off develop for every major new version (say 3.4), and update that branch to 3.4.1 etc ?
(Just puzzling why the 'master' exists, from a release theoretic point of view, if you don't need the extra complexity, by all means keep what works for you.)
If a bug is found in older version, and the users using it can't rightly update to bigger version (for example, it has some compatibility problems), then there's another branch created, e.g. "2.6.5", branching from last 2.6.4 commit in "master"; the bugs are fixed there, and the 2.6.5 update is released. The changes from 2.6.5 can then be merged to latest master.
Hypothetically, if there are other intermediate versions that have to be updated, similarily we may branch out of correspoinding point in history and merge the fixing branch there.

Sort of this:

Code: text

       2.6.5     3.0.1                 3.7.1
        *---------*---------------------*--------
       /         /                     /          
------*---------*---------------------*------------* -> go on with development
     2.6.4      3.0                   3.7


This is possible, although AFAIK was never used in AGS before, usually all bugs are fixed in the next version (if they still apply).
Since this is now open source project things may change.

Snarky

No particular opinion on this (different sub-version numbers for dev and release versions), as long as the numbers keep going up. I guess personally I'd mildly prefer not to have the second-level version update increment by two between every stable release, but as long as you pick a system you're happy with it doesn't seem like it really matters.

As for Alberth's objection about people "not understanding" that a later version isn't always better, it's common for open source projects to have a link to a stable release (which is what the default download button gives you) as well as to a wip version (whether it's called a beta, a development branch or whatever) with a higher version number. As long as they're clearly labeled and the default is set correctly (and the stable release doesn't lag the beta by too much), it shouldn't be a problem.

Alberth

Quote from: Crimson Wizard on Sat 20/09/2014 17:22:41
Quote from: Alberth on Sat 20/09/2014 16:53:35
After reading your older post about branches http://www.adventuregamestudio.co.uk/forums/index.php?topic=50001.0, I think 'develop' itself should not have a version number at all, you could use 0.0.0.<git-hash> if you need to build it.
This is the question of public version, not naming the branch. The branch can be named in any way which is convinient for developers; and if developers make some build for themselves, they can again call it as they please. However here we discuss the version as seen by users; and release version should have clear meaning for them. End-users don't know what "git-hash" is, how will they know this version is the next beta or whatnot?
I am aware of that.
I see a build of 'develop' as something for developers. It's generally useful to be able to build such a thing 'out of the box', that's why I attached a weird but unique number to it.

For public versions, I proposed to name it "next-version"-betaN, where "next-version" is the 2-number prefix of the last release, with the second number incremented by 1 (3.4 -> 3.5, 4.9 -> 4.10), and "N" incremented by one with each release.
Number would be assigned in a release branch.


Quote from: Crimson Wizard on Sat 20/09/2014 17:22:41
Sort of this:

Code: text

       2.6.5     3.0.1                 3.7.1
        *---------*---------------------*--------
       /         /                     /          
------*---------*---------------------*------------* -> go on with development
     2.6.4      3.0                   3.7


This is possible, although AFAIK was never used in AGS before, usually all bugs are fixed in the next version (if they still apply).
Since this is now open source project things may change.
Ah yes, you'd forward-port the fix to the newest releases too. That would make sense.

Crimson Wizard

Sorry, post deleted. I see your point.

Crimson Wizard

#154
Well, this needs to be resolved somehow...

Although I honestly see a certain benefit of BigMC's suggestion I am being held back by the consideration that this will be very uncommon for the most users of AGS.
My own personal opinion is to continue using same versioning scheme for now, but include fourth number to the public release (package) name as "development number" and reset it to 0 every time we change any of the first three. This way people would be able to clearly see the progress when we release intermediate WIP versions.
Of course, the "stage" releases, even fixing or updating existing versions, should have the third number changed (at least).
If we need to underline that the public release is WIP, we may add something to its package name (alpha, beta, rc), and stop doing that as soon as it reaches first stable version.

If later we will see that there are clearly problems with distinguishing between WIP and stable releases, we may consider using BigMC's suggestion, starting with 3.5 (which, conveniently, is a proper number for WIP version).

Regarding this
Quote from: Alberth on Sat 20/09/2014 18:19:35
Number would be assigned in a release branch.
Thing is that we start making "intermediate" WIP releases for public early in development, and we must number them somehow. IMHO choosing next "big" number (i.e. 3.5 after 3.4.* was released) is a logical thing.
(The highest number means "generation", and it rather supposes that we have rewritten a huge part of program from scratch. Such changes can't be applied on WIP branch with additions to previous version, because that makes little sense).
As for minor numbers, idea originally was to start developing them only when there's a need to quickly update one of the previously (recently or not) released version. Currently we have a "3.3.1" WIP, which is incorrect, and is actually my mistake breaking the rule I've proposed myself, and we plan to change it to 3.4.0.
Previously we've had a situation when we had 3.2.2 WIP version that was merged with more features, and we decided to not release 3.2.2, but change it to 3.3.0, and that is how it was finally released.

Calin Leafshade

Does it matter if it's uncommon for users?

All users care about is if the numbers go upwards. We don't make formal releases for dev releases anyway so most users will just use the stable version.


Alberth

Quote from: Calin Leafshade on Sun 21/09/2014 15:58:38
Does it matter if it's uncommon for users?

All users care about is if the numbers go upwards. We don't make formal releases for dev releases anyway so most users will just use the stable version.
Do you honestly believe that given a choice between 3.5.5 and 3.4.2, all users will pick 3.4.2?

Even if you have a few users making the wrong choice, you will end up with mess explaining to them they picked the wrong one, with a difficult explanation about odd and even numbers, etc.

Projects like a kernel are different; they have looooong development times, and many distributions (red-hat enterprise, centos, etc) stick to the last stable for 7+ years.
Also, unlike a user application like AGS, people don't generally install kernels themselves, they pick whatever their distribution provides. That means the public for a kernel is much more professional than Joe average Window user.

Crimson Wizard

#157
Quote from: Alberth on Sun 21/09/2014 16:09:45
Also, unlike a user application like AGS, people don't generally install kernels themselves, they pick whatever their distribution provides.
Well, to be honest, for AGS most people do install the version referenced from main website page. And when we post WIP versions on forum we warn that these are WIP.
I can't be sure whether they do or do not care what numbers are there...

E: Damn, I am too meek :). Now Calin made me doubt once again.

Retro Wolf

These hotfixes need to be advertised better. I didn't know there was a third hotfix until I just happened to need to redownload AGS.
I also remember talking to Adeel around the time of the second hotfix, he didn't know there was one.
We both spend a stupid amount of time on these forums.

Please don't take this as ungrateful, I appreciate the amount of work that goes into supporting this software.

Crimson Wizard

Quote from: Retro Wolf on Sun 21/09/2014 16:25:21
These hotfixes need to be advertised better. I didn't know there was a third hotfix until I just happened to need to redownload AGS.
I also remember talking to Adeel around the time of the second hotfix, he didn't know there was one.
We both spend a stupid amount of time on these forums.
Yes, this was my mistake, we will have a version change every time these are made from now on.

SMF spam blocked by CleanTalk