I'd like us to be a little more careful and deliberate about versioning
opencore.  We've started using CHANGES.txt but I think we could still use a
bit more structure there for it to be really useful.  As it is now, all
kinds of changes are checked in and written up with the same process, and we
rarely bother to increase the version number.  This means that releases, to
the extent they even exist, tend to be quite large and considerably
unfocused, containing all sorts of code-interface changes, new features, and
bugfixes in the same update.  If we move to a more structured system of
versions, it will be much easier for users of the code (whether internal or
external) to selectively choose their upgrades, install bugfixes without
being saddled with new features, and just generally have a better sense of
what's going on with our development.

If you're doing a significant and visible modification like extracting a
module out into a plugin package, doing a large-scale refactoring or
optimization, or adding a new feature, then please create a new minor
version for your work.  To do this:

 1) First, close out and release the previous unreleased bugfix version
x.x.n:
   A) Delete the "(unreleased)" text from the version line in the most
recent CHANGES.txt section;
   B) Append the current date to the version line;
   C) Upload it to the cheeseshop.   (That's `python setup.py register sdist
upload`; I'm not sure if everyone has properly permissioned accounts on
PyPI, but we'll fix that as it comes up.)

 2) Next, create a new minor version for your modifications and release it:
   A) Add your new minor-version section x.y to the top of CHANGES.txt;
   B) Check in your change and describe it briefly in the new section in
CHANGES.txt;
   C) Upload it to the cheeseshop.

 3) Finally, create a new unreleased bugfix-version section x.y.1 and just
check in CHANGES.txt with the new empty section.

Meanwhile, if you're just fixing a bug or doing a small refactoring, please
update the most recent section in CHANGES.txt with the change you made when
you are done.  As long as everyone follows the steps above, the most recent
section in CHANGES.txt should be an unreleased bugfix version (0.y.z
unreleased) so just append the description of your fix to the end of that
section's list of changes.

Note also that the points above directly imply that if you're working on a
change which will be big enough to merit a minor version increase, you
should either check in your entire change with a single commit (if it's
small enough) or do your intermediate work on a branch so that ongoing
bugfixes and minor tweaks can remain in the same purely-bugfix release.

I know the distinction I'm drawing is a little vague; just use your common
sense and if in doubt, or if you're not sure what I'm talking about here, do
feel free to ask me.  I realize this is a bit noisy, but it shouldn't take
more than five minutes at a time.  If it becomes too much of a hassle we can
think about automation strategies in the future but I'd rather try it out
before we start considering that.  All in all I think this will help us do a
better job of keeping track of what changes we're actually making and when.

Thanks,
egj

Attachments

text.html (text/html) 3.5 kB