How 'versions' work for Uzebox ?

Discuss general Uzebox topics here: features, wish list. nice to have, etc.
User avatar
filipe
Posts: 42
Joined: Thu Dec 17, 2009 10:37 pm
Location: Cambridge, UK

How 'versions' work for Uzebox ?

Post by filipe »

Actually I have more doubts about revisions, branches, releases, etc... I will start a new thread so we can discuss it.
-Filipe

I totally agree with you, it's a bit messy right now. However, I'd like to merge everything back in the trunk since the code is pretty solid now...
-Uze
That said, I would like to propose a discussion about create a new standard for versions and releases. So I wrote an draft. It is just a suggestion, I would like to hear from you if it is worth. If yes, after the contributions we can compile a entry in the wiki and use it like a simple guide.

The version number rules:
Simple solution using 2 fields:
0.0 (major and minor)

The "major" changes always with big changes or when the API changes breaking compatibility.
The "minor" changes for small implementations: best performance, bug fixes, new tools, new games, etc

The releases rules:
The releases are made when a group of implementations are ready in the trunk. They bump the version using the version rules.
A release is made by:
* Creating a new "tag" in SVN
* Creating a featured package

Note: There is no current standard on the package names: devkernel010310.zip, kernel.zip, uzebox-beta5-rev109.zip. Since the Uzebox is more than the kernel, the best name is the project's name followed by the version number. If a version is not closed but for some reason we want create a public package, we can use something like "dev" or "beta" followed by the SVN revision number. This way all the names are easy and anyone knows exactly where to find the code in the repository.
Examples:
uzebox-2_0.zip
uzebox-2_1.zip
uzebox-dev-rev118.zip
uzebox-3_0.zip

Trunk and branches rules:
Trunk contains the latest implementations done! It is supposed to be in good health (aka not broken :P).
New implementations can be done using branches. After to move the code to trunk, remove the branch.

Sub-projects:
Uzebox is composed by hardware, kernel, demos, tools, resource files. We have a release version, but how about the version of each sub-project ?
I'm not sure about this, keep using a global version is more simple and easy, but is weird for example if between versions 2.2 and 2.3 nothing changes for the kernel, but the schematic has changes. We have kernel 2.2 that is equal to kernel 2.3.
But it is ok if we think that we don't have kernel the kernel vesion xxx but we have the kernel from the Uzebox version 2.3 and looking the Changelog between 2.2 and 2.3 we know the kernel didn't change.

My vote is keep a global version, it is more simple. We can create a simple file like version.mk and include it in all the Makefiles.

The current status:

Trunk - Based on the README, it is 2.0-beta3
Branch/rev_beta4 - 2.0-Beta4
Branch/rev_beta5 - 2.0-Beta5

Sugestion,
Create a tag from trunk: 2.0.beta3
Commit branch beta4 to trunk and create a tag: 2.0.beta4
Commit branch beta5 to trunk and create a tag: 2.0.beta5
The next will be 2.1

Other details:
*Remove the version from the README file name, otherwise the file must be copied and deleted in the SVN each time.
*The packages are being created using the checkout svn command. This is not good because it contains the ".svn" directories. Use the command "svn export", it works like "checkout" but without the ".svn" directories.

-Filipe Rinaldi.
User avatar
uze6666
Site Admin
Posts: 4801
Joined: Tue Aug 12, 2008 9:13 pm
Location: Montreal, Canada
Contact:

Re: How 'versions' work for Uzebox ?

Post by uze6666 »

Hi Filipe,

I totally agree with your proposed draft. A few comments:
The "major" changes always with big changes or when the API changes breaking compatibility.
The "minor" changes for small implementations: best performance, bug fixes, new tools, new games, etc
Following this logic, minor would change when including a new video modes or simple feature?
Sub-projects:
To have the schematics in there still bugs me. I'm thinking about removing them because I don't want to mix hardware stuff with the code. Moreover the code in SVN should be generic to all Uzebox hardware clones. Finally, the main site links to local files, not to the files in SVN. Comments?
Sugestion,
Create a tag from trunk: 2.0.beta3
Commit branch beta4 to trunk and create a tag: 2.0.beta4
Commit branch beta5 to trunk and create a tag: 2.0.beta5
The next will be 2.1
The beta5 branch should become the trunk, its about time! :) The beta4 branch is redundant so it can be deleted. I'd say please tag the trunk with 2.0, and I propose the beta5 branch become a new major version "3.0" since it's a major overhaul compared with the trunk. After that we can continue 3.1, 3.2 etc.
*Remove the version from the README file name, otherwise the file must be copied and deleted in the SVN each time.
*The packages are being created using the checkout svn command. This is not good because it contains the ".svn" directories. Use the command "svn export", it works like "checkout" but without the ".svn" directories.
Agreed.

Any other comments?

Thank a lot Filipe for your time on this. I like where the project is heading!

-Uze
User avatar
Jhysaun
Posts: 214
Joined: Tue Nov 04, 2008 12:32 am

Re: How 'versions' work for Uzebox ?

Post by Jhysaun »

*The packages are being created using the checkout svn command. This is not good because it contains the ".svn" directories. Use the command "svn export", it works like "checkout" but without the ".svn" directories.

That would be my fault, I never really used SVN and checkout seemed to work. Ill use export next time :D

>J
Lerc wrote:I intend to use my powerful skills of procrastination to ensure that when I get to making things, the chips will be available.
User avatar
filipe
Posts: 42
Joined: Thu Dec 17, 2009 10:37 pm
Location: Cambridge, UK

Re: How 'versions' work for Uzebox ?

Post by filipe »

Following this logic, minor would change when including a new video modes or simple feature?
Good question, I don't know :D
I think it would be a new major version since it is relevant.
I'm thinking about removing them because I don't want to mix hardware stuff with the code
Sounds a good idea. And if some new HW is added (like Wii controls :lol:) it is ok to display a "Compatible with 'Uzebox SDK' >= 4.0" message.
The beta5 branch should become the trunk, its about time! The beta4 branch is redundant so it can be deleted. I'd say please tag the trunk with 2.0, and I propose the beta5 branch become a new major version "3.0" since it's a major overhaul compared with the trunk. After that we can continue 3.1, 3.2 etc.
Ok, I agree with you.

A new suggestion: Remove the '.hex' files from the SVN:
  • they bloat the source base
  • It easy to forget to update them when a new commit is made (they are out-of-date now!)
  • They slow down the source management
If the idea is still to offer them in one package (they are "downloable" from the wiki anyway), it's possible to make a binary release (emulator+demos).
Thank a lot Filipe for your time on this. I like where the project is heading!
It is an enjoyable project :D

-Filipe Rinaldi.
User avatar
uze6666
Site Admin
Posts: 4801
Joined: Tue Aug 12, 2008 9:13 pm
Location: Montreal, Canada
Contact:

Re: How 'versions' work for Uzebox ?

Post by uze6666 »

Good question, I don't know :D
I think it would be a new major version since it is relevant.
Yeah it would indeed be releveant, but not really major for a single mode (at least like mode 8, very trivial). I'd propose if significant load of features are added/changed or a rewrite of the kernel is done (breaking up compatibily as you mentionned) that would be worth a major version increase. Anything else, let's make it a minor increase.
Sounds a good idea. And if some new HW is added (like Wii controls :lol:) it is ok to display a "Compatible with 'Uzebox SDK' >= 4.0" message.
I'm wondering if I'll create another gCode project for schematics or simply host it on my domain...but changes are so rare, it's probably not worth it. I'll add a link in the google code project page pointing to the schematics download on the main site.
A new suggestion: Remove the '.hex' files from the SVN:

* they bloat the source base
* It easy to forget to update them when a new commit is made (they are out-of-date now!)
* They slow down the source management

If the idea is still to offer them in one package (they are "downloable" from the wiki anyway), it's possible to make a binary release (emulator+demos).
Totally agree. I wanted to provide easy access to compiled version of the games when people downloads the Uzebox "SDK". Providing binaries of the emulator and the demos would be the way to go. I know google can invoke some external URL when code is commited. That can be used to trigger external builds. I'm wondering if we could use this to build all configuration automatically (or manually on official releases). For sure I can't do that on my hosting provider though.

-Uze
User avatar
filipe
Posts: 42
Joined: Thu Dec 17, 2009 10:37 pm
Location: Cambridge, UK

Re: How 'versions' work for Uzebox ?

Post by filipe »

I know google can invoke some external URL when code is commited. That can be used to trigger external builds. I'm wondering if we could use this to build all configuration automatically (or manually on official releases). For sure I can't do that on my hosting provider though.
Starting from a simple solution, we can create a high-level Makefile to build "tools, games, SD image" to generate a binary release (.zip).
Later if it's possible in some way to trigger this build system from google: cool!
And, there are the ".hex" on the wiki. At least for the games in the Uzebox repository, you can use this "binary release" to put the games in a directory in the host and keep the .hex links pointing there. This way, it is easy to keep all the games always updated.

-Filipe.
User avatar
uze6666
Site Admin
Posts: 4801
Joined: Tue Aug 12, 2008 9:13 pm
Location: Montreal, Canada
Contact:

Re: How 'versions' work for Uzebox ?

Post by uze6666 »

And, there are the ".hex" on the wiki. At least for the games in the Uzebox repository, you can use this "binary release" to put the games in a directory in the host and keep the .hex links pointing there. This way, it is easy to keep all the games always updated.
That's good for the "demo" HEXes, however I'd like a more general repository approach where programmers could upload themselves their latest version. The Wiki would point to that and a function could allow to zip 'em all at once for download. Since my host supports PHP and also hosts this forum, I could code a simple upload application and use the forums ID as a single sign on. Just don't know when I'll get time for this! :( I guess the WIKI will do fine for now.

-Uze
User avatar
uze6666
Site Admin
Posts: 4801
Joined: Tue Aug 12, 2008 9:13 pm
Location: Montreal, Canada
Contact:

Re: How 'versions' work for Uzebox ?

Post by uze6666 »

Ok it's done!

-The trunk was tagged as uzebox-2.0
-Beta4 was deleted
-Beta5 replaced the trunk
-The new trunk was tagged uzebox-3.0

I also removed the HEX files as discussed, increased the emulator version and did some minor cleanup.

-Uze
User avatar
filipe
Posts: 42
Joined: Thu Dec 17, 2009 10:37 pm
Location: Cambridge, UK

Re: How 'versions' work for Uzebox ?

Post by filipe »

Great! I've created an entry in wiki: http://uzebox.org/wiki/index.php?title= ... Guideline)

-Filipe.
User avatar
filipe
Posts: 42
Joined: Thu Dec 17, 2009 10:37 pm
Location: Cambridge, UK

Re: How 'versions' work for Uzebox ?

Post by filipe »

paul wrote:However, it might be a good idea to have a branch for each tag so that any major bugs can be fixed for those releases and then a new tag like uzebox-2.1 can be made.
You mean do something like the GCC project ? http://gcc.gnu.org/develop.html
I think that is good for a big project, where you really need to support a specific version because the customers can't just change in every release. But for a small and not commercial project it depends. If the games can follow the trunk development, I think that bugs can be corrected in new versions. If they not, I agree with you :)

Anyway, the branch can be created from the tag, so it's not necessary to have them created before-hand now.

-Filipe.
Post Reply